FLUX.3 图像生成 API（flux-3-image）

DataEyes 开放平台 · 图像生成服务
Base URL：https://studio.dataeyes.ai

flux-3-image 是 Black Forest Labs 推出的 FLUX.3 图像模型，支持文生图、参考图编辑、多图融合（最多 10 张参考图）和框选布局。平台提供 OpenAI 兼容接口，同步返回结果，可直接使用 OpenAI SDK。

1. 基本信息

项	说明
文生图 / 参考图编辑	`POST /v1/images/generations`（JSON）
上传本地文件编辑	`POST /v1/images/edits`（multipart/form-data）
鉴权	`Authorization: Bearer <YOUR_API_KEY>`，API Key 在控制台「令牌管理」中创建
模型 ID	`flux-3-image`
计费	按次计费：每次成功生成 1 张计费 1 次，与分辨率、比例、参考图数量无关；请求失败不计费。单价以控制台「模型广场」为准
输出	每次固定 1 张，PNG
耗时	768sq / 1k 约 20 秒，1.5k / 2k 约 35 秒，4k 约 90 秒；带参考图约 30–60 秒。客户端超时建议设置为 180 秒以上

2. 请求参数（`/v1/images/generations`）

参数	类型	必填	说明
`model`	string	是	`flux-3-image`
`prompt`	string	是	画面描述，或对参考图的修改指令（参考图按传入顺序称为 Image 1、Image 2…）。支持中英文
`aspect_ratio`	string	否	宽高比：`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` `auto`。默认 `auto`：无参考图时由模型根据提示词决定，有参考图时沿用第 1 张参考图的比例
`resolution`	string	否	分辨率档位：`768sq` `1k` `1.5k` `2k` `4k`，默认 `1k`。按像素总量分档，具体宽高随比例变化（见第 3 节）
`size`	string	否	OpenAI 风格的 `宽x高`（如 `1792x1024`），会映射到最接近的比例和分辨率档位。推荐使用 `aspect_ratio` + `resolution`；与 `aspect_ratio` 同时传入时以 `aspect_ratio` 为准
`images`	string / string[]	否	参考图，1–10 张。每张可以是公网图片 URL、纯 Base64 或 `data:image/...;base64,...`。兼容旧字段名 `image`
`response_format`	string	否	`url`（默认）或 `b64_json`
`grounding`	boolean	否	是否允许模型联网检索（网页 + 图片）来理解提示词，默认 `true`，适合涉及真实人物、地点、品牌的提示词；设为 `false` 关闭
`safety_tolerance`	integer	否	内容审核宽松度，数值越大越宽松，默认 `2`。当前开放 0–4，超出范围返回 `422`

注意事项

n 参数不生效，每次固定返回 1 张。需要多张请并发发起多个请求。

seed、output_format、quality、style 等字段对本模型无效，传入会被忽略，不报错。

与 FLUX.2 / Kontext 系列的区别

项	flux-3-image	FLUX.2 / Kontext
控制尺寸	`aspect_ratio` + `resolution`	`size`
参考图字段	`images`（兼容 `image`），最多 10 张	`image`
`b64_json`	支持	不支持
`seed`	不支持	支持
响应	返回 `revised_prompt`（模型扩写后的提示词）	返回 `seed`

3. 分辨率档位与输出尺寸

resolution	像素总量	实测输出示例
`768sq`	约 0.6MP	1:1 → 768×768
`1k`（默认）	约 1MP	1:1 → 1024×1024；16:9 → 1360×768；9:16 → 768×1360；21:9 → 1568×672
`1.5k`	约 2.4MP	1:1 → 1536×1536；16:9 → 2048×1152
`2k`	约 4.2MP	1:1 → 2048×2048；3:4 → 1776×2368
`4k`	约 16.8MP	3:4 → 3552×4736

size 映射示例：1024x1024 → 1024×1024；1792x1024 → 2048×1152；2048x2048 → 2048×2048。

4. 示例

4.1 文生图（cURL）

4.2 参考图编辑 / 多图融合

{
  "model": "flux-3-image",
  "prompt": "Turn Image 1 in the style of Image 2",
  "images": [
    "https://example.com/photo.jpg",
    "data:image/png;base64,iVBORw0KGgo..."
  ]
}

单图编辑只传 1 张，prompt 写修改指令即可，如 "make the sky pink"。

4.3 Python（OpenAI SDK）

OpenAI 标准之外的参数放在 extra_body 中：

/v1/images/edits 上传多张图片时使用 image[] 字段；resolution、aspect_ratio 作为普通表单字段传入。

4.4 框选布局（指定元素位置）

在 prompt 末尾追加 JSON 数组，在正文中用 <id> 引用元素。bbox 格式为 [y0, x0, y1, x1]，取值 0–1000（相对画面）：

Minimal poster: a red circle <circle_1> on a white background <bg_1>. [{"id":"bg_1","bbox":[0,0,1000,1000],"desc":"plain white paper"},{"id":"circle_1","bbox":[100,100,400,400],"desc":"a solid red circle"}]

5. 响应

{
  "created": 1792135130,
  "data": [
    {
      "url": "https://storage.example.com/.../sample.png?se=...&sig=...",
      "revised_prompt": "Studio photograph, shot head-on from table height ..."
    }
  ]
}

字段	类型	说明
`created`	integer	完成时间（Unix 秒级时间戳）
`data`	array	生成结果，固定 1 个元素
`data[].url`	string	图片临时下载链接，约 1 小时后失效，请立即下载转存
`data[].b64_json`	string	`response_format` 为 `b64_json` 时返回，替代 `url`
`data[].revised_prompt`	string	模型扩写后的实际提示词

6. 错误码

错误响应格式：{"error": {"message": "...", "code": "..."}}。失败请求不计费。

HTTP	场景	message 示例
401	API Key 无效	—
422	缺少 `prompt`	`body/prompt: Field required`
422	`resolution` 取值非法	`body/resolution: Input should be '768sq', '1k', '1.5k', '2k' or '4k'`
422	`aspect_ratio` 取值非法	`body/aspect_ratio/...: Input should be '21:9', ...`
422	`safety_tolerance` 超出开放范围	`safety_tolerance_not_approved`
400	参考图 URL 无法访问	`Unable to extract dimensions from input image: ...404 Not Found...`

7. 使用建议

计费暂不区分分辨率，需要高清图可直接使用 2k / 4k。

参考图 URL 必须公网可访问；内网或需要鉴权的图片请改传 Base64。

提示词中要出现文字时，用引号写出原文并说明位置，如 a poster on the wall that reads "OPEN LATE"。

使用原生 HTTP 库调用时请设置 User-Agent 请求头（OpenAI SDK、curl 默认已带），否则可能返回 403。

FLUX.3 图像生成 API（flux-3-image）

1. 基本信息#

2. 请求参数（/v1/images/generations）#

3. 分辨率档位与输出尺寸#

4. 示例#

4.1 文生图（cURL）#

4.2 参考图编辑 / 多图融合#

4.3 Python（OpenAI SDK）#

4.4 框选布局（指定元素位置）#

5. 响应#

6. 错误码#

7. 使用建议#