FLUX.2 Pro API
POST
/v1/tasks 所有模型都通过 统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。
模型概览
| 模型名称 | flux-2/text-to-image |
|---|---|
| 类型 | 图像生成（文生图） |
| 接口 | POST /v1/tasks |
| 价格 | 见 HiAPI 定价 |
Black Forest Labs 旗舰文生图模型：照片级高保真与稳定打光，复杂多元素指令遵循度高，图内小字号文字清晰可读并支持 hex 色号精确控色，按 0.5-4 MP 分辨率档计价。
生产建议
生产环境建议
- 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
- GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
- callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。
适用场景
产品图与商业摄影质感
更锐利的材质纹理与稳定打光适合电商产品图和广告静物；写实场景在提示词中加入相机、镜头、胶片描述（如 "Shot on Fujifilm X-T5, 35mm f/1.4"）质感更可控。
promptresolution含文字的海报与 UI mockup
官方称小字号文本渲染可靠，适合带标题的海报、信息图与 UI mockup；把文字内容和排版位置直接写进提示词即可。
promptaspect_ratio品牌精确控色
支持在提示词中用 hex 色号（如 #3B2A1A）指定颜色，品牌主视觉与 VI 物料可精确对齐色板，不再依赖"深棕色"这类模糊描述。
prompt复杂多元素构图
对多部分指令和组合约束（元素位置、相互关系）的遵循显著改善，复杂场景还可用 JSON 结构化提示词描述；固定 seed 便于迭代时保持构图稳定。
promptseed请求参数
model string 必填 固定填 flux-2/text-to-image。
input object 必填 业务参数对象；FLUX.2 Pro 的模型专属配置都放在这里。
prompt string 必填 图像生成提示词。官方建议把重要元素放在句首（词序影响权重），30-80 词效果最佳。
aspect_ratio enum 可选 生成图像的宽高比；选 custom 时配合 width/height 指定精确尺寸。
width integer 可选 自定义宽度，仅 aspect_ratio=custom 时生效，256-2048，自动取整到 16 的倍数。
height integer 可选 自定义高度，仅 aspect_ratio=custom 时生效，256-2048，自动取整到 16 的倍数。
resolution enum 可选 输出分辨率档位（百万像素），最高 4 MP；aspect_ratio=custom 时忽略此参数。托管方建议 2 MP 及以下效果更稳。
output_format enum 可选 输出图片格式。
output_quality integer 可选 保存图片时的压缩质量，0-100；仅对 webp/jpg 有损格式生效，png 无效。
safety_tolerance integer 可选 内容安全宽松度：1 最严格，5 最宽松，默认 2。
seed integer 可选 随机种子；固定后可复现生成结果。
callback object 可选 可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。
url string 必填 传入 callback 时必填；接收任务终态通知的 HTTPS 地址。
when enum 可选 回调触发时机；当前建议固定为 final。
用例示例
带文字与 hex 控色的品牌海报
标题文字、副标题和三个 hex 色号直接写进提示词，验证文字渲染与精确控色；png 格式避免文字边缘压缩损失。
请求体
{
"model": "flux-2/text-to-image",
"input": {
"prompt": "A minimalist coffee brand poster: a matte ceramic pour-over cup of black coffee with a thin curl of steam, headline 'MORNING RITUAL' in large elegant uppercase serif type in deep espresso brown #3B2A1A, subheading 'SLOW BREW · SMALL BATCH' in a thin sans-serif in soft taupe #8A7660, vast warm beige background #EDE3D2 with generous negative space, soft window light from the upper left, modern editorial product photography",
"aspect_ratio": "2:3",
"resolution": "2 MP",
"output_format": "png"
}
}黄金时刻写实人像
用胶片、镜头与光圈描述法（Kodak Portra 400、85mm f/1.8）控制写实质感与景深。
请求体
{
"model": "flux-2/text-to-image",
"input": {
"prompt": "A young woman in profile, face turned three-quarters toward warm light, loose strands of hair drifting across her cheek, calm unguarded expression. Cinematic realistic portrait on a quiet open field at dusk, backlit by low golden-hour sun with rim light glowing amber through flyaway hair. Shot on Kodak Portra 400, 85mm lens at f/1.8, shallow depth of field, natural film grain, warm organic palette",
"aspect_ratio": "4:5",
"resolution": "1 MP"
}
}custom 尺寸电商产品图
aspect_ratio=custom 配合 width/height 指定精确像素（256-2048，自动取整到 16 的倍数），此时 resolution 参数被忽略。
请求体
{
"model": "flux-2/text-to-image",
"input": {
"prompt": "Matte black wireless over-ear headphones standing upright on a glossy dark acrylic surface, rim-lit edges, soft gradient charcoal background, studio product photography, 100mm macro lens at f/5.6, crisp reflections and fine texture detail",
"aspect_ratio": "custom",
"width": 1200,
"height": 1600
}
}获取结果
- 提交成功后立即返回 taskId（不等待生成完成）。
- 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
- status=success 后，从返回的 output[].url 下载生成的图片。
- 如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。
常见问题
FLUX.2 Pro 的价格怎么算？
按 resolution 分辨率档位计费，0.5 MP / 1 MP / 2 MP / 4 MP 共四档，档位越高单价越高；宽高比不影响价格。实时价格以定价页为准。 查看实时价格
为什么没有 negative_prompt 参数？
FLUX.2 不支持 negative prompt。在提示词里写"不要出现 X"这类否定词可能适得其反——模型反而会把该元素画进去。正确做法是正向描述想要的内容，并把重要元素放在句首。
分辨率档怎么选？
托管方建议 2 MP 及以下效果更稳，日常出图选 1-2 MP 即可；4 MP 留给印刷级交付。注意单边像素上限 2048，非方形比例下最高档的实际像素可能达不到目标 MP 值。
custom 尺寸怎么用？
把 aspect_ratio 设为 custom，再传 width 和 height（256-2048），系统会自动取整到 16 的倍数；此时 resolution 参数被忽略。只在需要精确像素时使用，常规场景用预设比例加 resolution 档位即可。