# FLUX 图像生成
> 文生图、单图编辑、多图参考
> 支持在提示词里用 bbox 精确控制版式
> 输出档位从 768 到 4K
`POST /v1/images/generations`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求结构
请求体是平铺的 JSON，创作字段与输出字段都在顶层，没有 `content` 数组包装。
## 支持的场景
| 场景 | 字段组合 |
|---|---|
| 文生图 | `prompt` |
| 单图编辑 | `prompt` + `image`（1 张） |
| 多图参考 | `prompt` + `image`（2 到 10 张） |
| 版式控制 | `prompt` 内含 bbox JSON 数组 |
参考图按顺序编号为 `ref_image_0`、`ref_image_1`，提示词里也可以写成 `Image 1`、`Image 2`。
## 请求参数
> **Note:** 
> 提交成功只返回任务 ID，不含图片本身。拿结果用 `task_id` 轮询[获取任务状态](../tasks/status.html)，图片地址在 `result.images[0].url`，该地址会过期，请及时转存。
- `model` (string / 必填) — 取值 `flux-3-image`。
- `prompt` (string / 必填) — 场景描述或编辑指令。 不支持反向提示词，请正面描述想要的结果。可以在提示词里带 `<tag>` 元素引用与 bbox JSON 数组，用于控制版式或局部编辑。
- `image` (string | string[] / 可选) — 参考图，1 到 10 张。公网地址或 Base64。超过 10 张返回 400。 传入即由文生图切换为编辑或多图参考。
- `aspect_ratio` (string / 可选) — 画幅，默认 `auto`。 取值 `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`，也接受 `16x9` 写法。
- `resolution` (string / 可选) — 输出档位，取值 `768sq`、`1k`（默认）、`1.5k`、`2k`、`4k`，大小写不敏感。 `768` 等同 `768sq`。该字段同时决定计费档。
- `safety_tolerance` (integer / 可选) — 内容宽松度，取值 0 到 4，默认 `2`，数值越大越宽松。
- `grounding` (boolean / 可选) — 允许生成前联网或检索图片，默认 `true`。必须是布尔值，传字符串 `"false"` 会返回 400。
- `n` (integer / 可选) — 只能为 `1`。需要多张请分多次提交。
## 不接受的字段
`width`、`height`、像素形式的 `size`（如 `1024x1024`）、`seed`、`steps`、`guidance`、`output_format`、`negative_prompt`、`prompt_upsampling`、`mask_url` 都会被拒绝并返回 400，不会静默忽略。
输出尺寸用 `resolution` 控制，形状用 `aspect_ratio` 控制。
## bbox 版式控制
bbox 是提示词字符串的一部分，不是独立参数。每个元素用 `id`、`from`、`src_bbox`、`tgt_bbox`、`desc` 描述。
坐标格式是 `[top, left, bottom, right]`，即 `[y1, x1, y2, x2]`，归一化到 0 到 1000，原点在左上角，不是像素值。
需要保留的区域也要写进 bbox，并在 `desc` 里说明保持不变。
## Kontext 系列的差异
`flux-kontext-pro` 与 `flux-kontext-max` 支持 `output_format`、`response_format`、`seed`、`prompt_upsampling`、`safety_tolerance`（0 到 6），但不支持 `resolution`，输出固定在约 1MP。`size` 写像素时只会映射到最接近的支持比例，不保证精确尺寸。
## 响应
提交成功返回受理结构：
```json
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
- `code` (integer / 总是返回) — 状态码，`200` 表示任务已受理。
- `data` (array / 总是返回) — 本次提交的任务列表。
- `data[].status` (string / 总是返回) — 受理状态，提交成功时为 `submitted`。
- `data[].task_id` (string / 总是返回) — 任务 ID，用它轮询结果。
完成态返回：
```json
{
  "code": 200,
  "data": {
    "id": "task_01K8SGYNNNVBQTXNR4MM964S7K",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        { "url": ["https://cdn.oairoute.com/f/image/task_01K8_0.png"], "expires_at": 1763174708 }
      ]
    },
    "created": 1763088289,
    "completed": 1763088302
  }
}
```
## 错误码
| HTTP | 含义 |
|---|---|
| 400 | 参数错误，type 为 invalid_request_error |
| 401 | Token 缺失或无效，type 为 authentication_error |
| 402 | 余额不足，type 为 payment_required |
| 429 | 触发限流 |
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 支持的模型列表
| 模型 ID | 定位 |
|---|---|
| `flux-3-image` | 主力型号，支持文生图、编辑、多图参考与版式控制 |
`flux-kontext` 系列走同一路径但参数不同，见下方差异说明。
> **Note:** 完整模型目录（含价格、分辨率上限）可读取 `GET https://api.oairoute.com/api/pricing`。
## 使用示例
**文生图{Text to image}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "flux-3-image",
  "prompt": "沙漠中的公路，热浪扭曲空气，镜头低角度前进",
  "aspect_ratio": "21:9",
  "resolution": "2k"
}'
```
**文生图{Text to image}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "flux-3-image",
  "prompt": "沙漠中的公路，热浪扭曲空气，镜头低角度前进",
  "aspect_ratio": "21:9",
  "resolution": "2k"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**文生图{Text to image}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "flux-3-image",
  "prompt": "沙漠中的公路，热浪扭曲空气，镜头低角度前进",
  "aspect_ratio": "21:9",
  "resolution": "2k"
}),
});
console.log(await res.json());
```
**200 文生图{Text to image}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**单图编辑{Image edit}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "flux-3-image",
  "prompt": "把天空换成暴雨将至的乌云",
  "image": [
    "https://example.com/landscape.jpg"
  ],
  "aspect_ratio": "auto"
}'
```
**单图编辑{Image edit}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "flux-3-image",
  "prompt": "把天空换成暴雨将至的乌云",
  "image": [
    "https://example.com/landscape.jpg"
  ],
  "aspect_ratio": "auto"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**单图编辑{Image edit}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "flux-3-image",
  "prompt": "把天空换成暴雨将至的乌云",
  "image": [
    "https://example.com/landscape.jpg"
  ],
  "aspect_ratio": "auto"
}),
});
console.log(await res.json());
```
**200 单图编辑{Image edit}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**多图参考{Multi reference}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "flux-3-image",
  "prompt": "把 Image 1 的人物放进 Image 2 的场景",
  "image": [
    "https://example.com/person.jpg",
    "https://example.com/scene.jpg"
  ]
}'
```
**多图参考{Multi reference}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "flux-3-image",
  "prompt": "把 Image 1 的人物放进 Image 2 的场景",
  "image": [
    "https://example.com/person.jpg",
    "https://example.com/scene.jpg"
  ]
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**多图参考{Multi reference}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "flux-3-image",
  "prompt": "把 Image 1 的人物放进 Image 2 的场景",
  "image": [
    "https://example.com/person.jpg",
    "https://example.com/scene.jpg"
  ]
}),
});
console.log(await res.json());
```
**200 多图参考{Multi reference}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**4K 输出{4K output}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "flux-3-image",
  "prompt": "雪山脊线，长焦压缩感，冷调",
  "aspect_ratio": "3:2",
  "resolution": "4k"
}'
```
**4K 输出{4K output}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "flux-3-image",
  "prompt": "雪山脊线，长焦压缩感，冷调",
  "aspect_ratio": "3:2",
  "resolution": "4k"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**4K 输出{4K output}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "flux-3-image",
  "prompt": "雪山脊线，长焦压缩感，冷调",
  "aspect_ratio": "3:2",
  "resolution": "4k"
}),
});
console.log(await res.json());
```
**200 4K 输出{4K output}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```