# Wan 图像生成
> 文生图、图像编辑、多图参考
> 支持组图模式，一次最多 12 张
> 可指定调色板与 bbox 局部编辑
`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` |
| 多图参考 | `prompt` + `image`（多张） |
| 局部编辑 | `prompt` + `image` + `bbox_list` |
| 组图 | `enable_sequential: true` + `n` |
| 指定配色 | `prompt` + `color_palette` |
带 `image` 时输出比例静默跟随最后一张输入图，且上限压到 2K，无法出 4K。
## 请求参数
> **Note:** 
> 提交成功只返回任务 ID，不含图片本身。拿结果用 `task_id` 轮询[获取任务状态](../tasks/status.html)，图片地址在 `result.images[0].url`，该地址会过期，请及时转存。
- `model` (string / 必填) — 取值 `wan2.7-image-pro` 或 `wan2.7-image`。 `-pro` 在文生图下最高支持 4K，编辑与组图上限 2K；标准版全部最高 2K。
- `prompt` (string / 必填) — 画面描述，上限 5000 字符。文生图必填，编辑模式建议填写。
- `image` (string | string[] / 可选) — 参考图，最多 9 张。公网地址或 Base64。 格式 JPEG、PNG、WEBP、BMP，单边 240 到 8000 像素，比例 1:8 到 8:1，单张不超过 20MB。传入即进入编辑模式。
- `n` (integer / 可选) — 生成张数，默认 `1`。普通模式 1 到 4；开启 `enable_sequential` 后 1 到 12。
- `size` (string / 可选) — 三种写法：档位 `1K`、`2K`、`4K`；比例 `1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`（按 2K 解析）；或精确像素 `1024x1024`。
- `resolution` (string / 可选) — 档位 `1K`、`2K`、`4K`，可与 `size` 里的比例组合。 `-pro` 文生图范围 768×768 到 4096×4096；编辑、组图与标准版上限 2048×2048。
- `negative_prompt` (string / 可选) — 反向描述，写不希望出现的内容。
- `watermark` (boolean / 可选) — 是否在右下角加 AI 生成标识，默认 `false`。
- `seed` (integer / 可选) — 随机种子，取值 0 到 2147483647。相同种子与参数风格趋近一致。
- `thinking_mode` (boolean / 可选) — 额外推理以改善构图，默认 `true`。 只在非组图且无输入图时生效。
- `enable_sequential` (boolean / 可选) — 组图模式，输出多张连贯画面，适合漫画与分镜，默认 `false`。 开启后会关闭 `thinking_mode` 与 `color_palette`，并将上限压到 2K。
- `bbox_list` (array / 可选) — 局部编辑的框选区域，嵌套形式 `[[[x1,y1,x2,y2],...],...]`。 外层长度必须与 `image` 一致，无需框选的图传 `[]`，每张最多 2 个框，使用原图像素坐标，原点在左上角。
- `color_palette` (array / 可选) — 调色板，3 到 10 项，每项含十六进制色值与占比。 占比合计必须正好为 100.00%。仅非组图模式可用。
## 计费
按成功生成的张数乘以单价计费，输入不计费。分辨率与比例不影响价格，失败任务不计费。
## 响应
提交成功返回受理结构：
```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 | 定位 |
|---|---|
| `wan2.7-image-pro` | 画质优先，文生图最高 4K |
| `wan2.7-image` | 标准版，速度更快，全部模式最高 2K |
> **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": "wan2.7-image-pro",
  "prompt": "小花店，窗框纤细，木门，午后阳光",
  "size": "4:3",
  "resolution": "4K"
}'
```
**文生图{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": "wan2.7-image-pro",
  "prompt": "小花店，窗框纤细，木门，午后阳光",
  "size": "4:3",
  "resolution": "4K"
}
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": "wan2.7-image-pro",
  "prompt": "小花店，窗框纤细，木门，午后阳光",
  "size": "4:3",
  "resolution": "4K"
}),
});
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": "wan2.7-image",
  "prompt": "把墙面换成浅米色，家具保持不变",
  "image": [
    "https://example.com/room.jpg"
  ]
}'
```
**图像编辑{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": "wan2.7-image",
  "prompt": "把墙面换成浅米色，家具保持不变",
  "image": [
    "https://example.com/room.jpg"
  ]
}
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": "wan2.7-image",
  "prompt": "把墙面换成浅米色，家具保持不变",
  "image": [
    "https://example.com/room.jpg"
  ]
}),
});
console.log(await res.json());
```
**200 图像编辑{Image edit}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**局部编辑{Regional 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": "wan2.7-image",
  "prompt": "在这个区域放进一盆绿植",
  "image": [
    "https://example.com/room.jpg"
  ],
  "bbox_list": [
    [
      [
        989,
        515,
        1138,
        681
      ]
    ]
  ]
}'
```
**局部编辑{Regional edit}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "wan2.7-image",
  "prompt": "在这个区域放进一盆绿植",
  "image": [
    "https://example.com/room.jpg"
  ],
  "bbox_list": [
    [
      [
        989,
        515,
        1138,
        681
      ]
    ]
  ]
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**局部编辑{Regional 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": "wan2.7-image",
  "prompt": "在这个区域放进一盆绿植",
  "image": [
    "https://example.com/room.jpg"
  ],
  "bbox_list": [
    [
      [
        989,
        515,
        1138,
        681
      ]
    ]
  ]
}),
});
console.log(await res.json());
```
**200 局部编辑{Regional edit}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**组图{Sequential set}::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": "wan2.7-image",
  "prompt": "四格分镜：清晨出门、街角咖啡、雨后归途、夜晚灯下",
  "enable_sequential": true,
  "n": 4,
  "size": "16:9"
}'
```
**组图{Sequential set}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "wan2.7-image",
  "prompt": "四格分镜：清晨出门、街角咖啡、雨后归途、夜晚灯下",
  "enable_sequential": true,
  "n": 4,
  "size": "16:9"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**组图{Sequential set}::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": "wan2.7-image",
  "prompt": "四格分镜：清晨出门、街角咖啡、雨后归途、夜晚灯下",
  "enable_sequential": true,
  "n": 4,
  "size": "16:9"
}),
});
console.log(await res.json());
```
**200 组图{Sequential set}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```
**指定配色{Color palette}::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": "wan2.7-image-pro",
  "prompt": "品牌海报，几何构成",
  "color_palette": [
    {
      "hex": "#1E3A8A",
      "ratio": 60.0
    },
    {
      "hex": "#F59E0B",
      "ratio": 25.0
    },
    {
      "hex": "#F5F5F4",
      "ratio": 15.0
    }
  ],
  "size": "2K"
}'
```
**指定配色{Color palette}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "wan2.7-image-pro",
  "prompt": "品牌海报，几何构成",
  "color_palette": [
    {
      "hex": "#1E3A8A",
      "ratio": 60.0
    },
    {
      "hex": "#F59E0B",
      "ratio": 25.0
    },
    {
      "hex": "#F5F5F4",
      "ratio": 15.0
    }
  ],
  "size": "2K"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**指定配色{Color palette}::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": "wan2.7-image-pro",
  "prompt": "品牌海报，几何构成",
  "color_palette": [
    {
      "hex": "#1E3A8A",
      "ratio": 60.0
    },
    {
      "hex": "#F59E0B",
      "ratio": 25.0
    },
    {
      "hex": "#F5F5F4",
      "ratio": 15.0
    }
  ],
  "size": "2K"
}),
});
console.log(await res.json());
```
**200 指定配色{Color palette}**
```
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
    }
  ]
}
```