FLUX.3 图片生成与编辑

公开模型名为 flux-3-image。使用同一个模型名，通过 resolution 选择分辨率，支持文生图、参考图编辑和异步任务。

每个请求生成 1 张图片，编辑最多使用 10 张参考图。不支持 mask，请在 prompt 中描述需要修改或保留的内容。

参数

尺寸与比例规则

• 档位优先级：resolution（或 image_size）> size 推断出的档位 > 默认 1.5K。
• size=16:9 只指定比例，不指定档位；可搭配 resolution=2K。
• size=宽x高 同时推断比例和档位。比例需接近支持值；显式传入 aspect_ratio 时，它必须与 size 的比例一致，否则返回参数错误。
• size=auto 不指定档位或比例。显式档位与 size 搭配时，size 仍用于确定比例。
• 模型按档位与比例出图，不保证严格返回请求的像素数。同步响应的 size 是图片的实际宽高；异步图片可在下载后读取实际宽高。

支持的比例：21:9、2:1、16:9、3:2、7:5、4:3、5:4、1:1、4:5、3:4、5:7、2:3、9:16、1:2、9:21。

同步文生图

先在环境变量中设置本站 API 地址和你的 API Key。本站文档页面会显示对应域名：

export API_BASE="https://api.modeltap.net/v1"
export API_KEY="YOUR_API_KEY"

生成 2K 横图并返回下载链接：

curl --max-time 900 "$API_BASE/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image",
    "prompt": "一台银色咖啡机置于木质桌面，柔和晨光，产品摄影",
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "n": 1,
    "response_format": "url",
    "output_format": "jpeg",
    "output_compression": 85
  }'

同步请求会等待出图。批量任务或网络连接不稳定时，可使用下文的异步接口。

参考图编辑

JSON：使用图片链接

图片需为公网可直接访问的 HTTPS 链接，支持 PNG / JPEG / WEBP。需要授权的私有文件请使用有效的签名链接。图片链接不能依赖登录、Cookie、请求头或重定向。

curl --max-time 900 "$API_BASE/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image",
    "prompt": "将第一张图的产品放入第二张图的场景，保持产品外观和标识",
    "images": [
      "https://cdn.example.com/product.png",
      "https://cdn.example.com/background.jpg"
    ],
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "response_format": "url"
  }'

请把示例图片链接替换为自己的可访问图片。images 中也可以传 data:image/png;base64,... 等 data URL，或 {"image_url": "https://..."} 对象。

单张参考图不超过 25 MB，下载的参考图合计不超过 64 MB。上传文件和 data URL 还受本站整个请求体大小限制；建议每张压缩到 2 MB 以内。完整链接和 data URL 规则见图片生成接口的参考图说明。

multipart：上传本地图片

curl --max-time 900 "$API_BASE/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=flux-3-image" \
  -F "prompt=将第一张图的产品放入第二张图的场景，保持产品外观和标识" \
  -F "image[]=@product.png" \
  -F "image[]=@background.jpg" \
  -F "resolution=2K" \
  -F "aspect_ratio=16:9" \
  -F "response_format=url"

单张图片可用 -F "image=@input.png"。一个请求选择 JSON 或 multipart 其中一种格式。

同步响应

response_format=b64_json 的响应示例：

{
  "created": 1791800000,
  "data": [{"b64_json": "iVBORw0KGgo..."}],
  "size": "1536x1536",
  "output_format": "png"
}

上面的像素尺寸仅作示例，以实际响应为准。将 data[0].b64_json 解码即可得到图片文件；展示时的 MIME 类型应与 output_format 一致。

response_format=url 时，data[0] 改为 {"url": "https://..."}，其余图片信息保持一致。下载链接有效期约 2 小时，请及时下载或转存。

异步任务

异步接口支持相同的生成、尺寸、编码和参考图参数，提交后返回 202 与任务 ID。

curl "$API_BASE/images/generations/async" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image",
    "prompt": "一台银色咖啡机置于木质桌面，柔和晨光，产品摄影",
    "resolution": "1.5K",
    "aspect_ratio": "1:1"
  }'

{
  "id": "nximg_xxxxxxxx",
  "status": "queued",
  "created": 1791800000,
  "object": "image.generation.async"
}

异步编辑只需将上文编辑示例的路径改为 /images/edits/async。输入图片在提交时下载或上传，因此签名参考图链接只需在提交时有效。

用返回的 ID 查询任务，建议每 2–5 秒轮询一次：

export JOB_ID="nximg_xxxxxxxx"
curl "$API_BASE/images/generations/async/$JOB_ID" \
  -H "Authorization: Bearer $API_KEY"

编辑任务也可通过 GET /v1/images/edits/async/{job_id} 查询。状态为 queued → processing → succeeded 或 failed；成功时从 data[0].url 下载图片，失败时读取 error。异步接口始终返回链接，即使提交时指定了 response_format=b64_json。

计费与错误处理

flux-3-image 按成功请求数量和所选分辨率档位计费。当前 n=1，一次成功请求生成一张图片：

• 文生图和参考图编辑使用对应档位的每请求单价。
• 提示词和参考图包含在该次请求中，不另外按 token 收费。
• 失败请求、失败任务和参考图校验失败不计费；异步提交成功不代表已出图，以任务最终状态为准。
• 单价和企业折扣以本站我的定价为准，不使用响应中的 token 数计算 FLUX.3 费用。

尺寸或比例冲突、非法档位、n 不为 1 时请修正参数；参考图超过 10 张或传入 mask 时请减少参考图、去掉 mask。遇到 429 或上游暂时不可用时降低并发并退避重试；同步超时可改用异步任务，并保留 X-Request-ID 便于查询。