# 生成图像（OpenAI 兼容）
> Seedream 5.0 的文生图、单图编辑、多图融合、组图、图层拆分
> 走 OpenAI Images 结构，现有 SDK 只改 base_url
> 同步返回，一次响应给出全部结果
`POST /v1/images/generations`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 Seedream 系列的接口需要在 [ark 站](https://ark.oairoute.com/) 单独获取 Key，与 api 站的 Key 不通用。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_ARK_KEY ```
## 请求结构
请求体与 `POST /doubao/api/v3/images/generations` 相同，区别只在路径与 `response_format` 的可用取值。
客户端已按 OpenAI Images API 编写时使用本路径。相比原生路径多两点能力：
- 支持 `response_format: b64_json`，网关会下载生成的图片并内联返回。
- 支持 `multipart/form-data`，参考图可以上传文件而不必用 URL。
`n` 必须为 `1`。需要多张请用 `sequential_image_generation`，不要再靠 `n`。
**文生图、图生图还是多图融合，只由 `image` 字段决定：**
| 场景 | `image` |
|---|---|
| 文生图 | 不传 |
| 单图编辑 | 字符串，公网 URL 或 `data:` URI |
| 多图融合 | 字符串数组，最多 10 张 |
## 支持的场景
| 场景 | 字段组合 |
|---|---|
| 文生图 | `prompt` |
| 文生图-指定像素 | `prompt` + `size: "2048x2048"` |
| 单图编辑 | `prompt` + `image`（字符串） |
| 多图融合 | `prompt` + `image`（2 到 10 张数组） |
| 按坐标编辑 | `prompt` 中带 `[x1, y1, x2, y2]` 坐标 + `image` |
| 生成组图 | `sequential_image_generation: "auto"` + `sequential_image_generation_options.max_images` |
| 内联 Base64 输出 | `response_format: "b64_json"` |
| 图层拆分 | `image`（恰好 1 张）+ `layer_decomposition: true` |
| 透明背景 | `image`（1 张）+ `background: transparent` + `output_format: png` |
## 请求参数
- `model` (string / 必填) — 图像模型 ID，必须写全名。取值见下方模型列表。 `seedream-5` 之类的缩写会返回 400。
- `prompt` (string / 条件必填) — 图像描述。图生图时描述你想要的改动；`layer_decomposition` 为 `true` 时可不传。
- `image` (string | string[] / 可选) — 参考图。每一项是公网 URL 或格式小写的 `data:image/<format>;base64,...` URI。最多 10 张，单张不超过 30MB。 **从第二张参考图起额外计费。**
- `size` (string / 可选) — 输出尺寸，两种写法二选一：档位 `1K`、`1.5K`、`2K`；或具体像素 `宽x高`，范围 `1024x1024` 到 `4096x4096`，宽高比 1:16 到 16:1。默认 `2K`。 `layer_decomposition` 为 `true` 时只接受 `1K`、`1.5K`、`2K` 或 `auto`，通常用 `auto`。
- `response_format` (string / 可选) — 默认 `url`，返回有效期 24 小时的临时链接，需要留存请及时下载。 `b64_json` 直接返回 Base64 内容。
- `watermark` (boolean / 可选) — 默认 **`true`**，为 `true` 时在右下角添加「AI 生成」水印。需要无水印必须显式传 `false`。
- `seed` (integer / 可选) — 随机种子，用于复现结果，取值 `-1` 到 `2147483647`，`-1` 为随机。
- `guidance_scale` (number / 可选) — 提示词遵循强度，值越高越严格贴合提示词。
- `output_format` (string / 可选) — 输出图片格式，取值 `jpeg`（默认）或 `png`。
- `background` (string / 可选) — `opaque`（默认）为正常背景；`transparent` 为透明背景，要求恰好一张参考图，且不能与 `output_format: jpeg` 同时使用，搭配 `output_format: png` 使用。
- `optimize_prompt` (boolean / 可选) — 生成前由模型扩写并优化提示词。
- `optimize_prompt_options` (object / 可选) — 提示词优化设置，仅在启用提示词优化时生效。 `mode` 取 `standard` 使用完整优化器；取 `fast` 使用快速优化器，仅 `doubao-seedream-5-0-pro-260628` 支持。
- `layer_decomposition` (boolean / 可选) — 默认 `false`。把输入拆成底图与若干独立图层。要求恰好一张参考图，每个输出图层单独计费。为 `true` 时 `prompt` 可省略。
- `n` (integer / 可选) — 只能是 `1`。传大于 1 会返回 400；需要多张请改用 `sequential_image_generation`。
- `sequential_image_generation` (string / 可选) — 取值 `auto` 开启组图，或 `disabled` 关闭。配合 `sequential_image_generation_options.max_images` 控制张数，参考图与生成图合计不超过 15 张。
- `stream` (boolean / 可选) — **不支持**，已废弃。网关始终一次性返回完整 JSON，传 `true` 会被拒绝。
## 尺寸与像素
**档位：** `1K`、`1.5K`、`2K`，默认 `2K`。
**精确像素：** 宽高各自须落在 `1024` 到 `4096` 之间，宽高比须在 1:16 到 16:1 之间。
限制的是单边与比例，不是乘积：`1024x1024` 合法，`512x512` 会返回 400。
## 响应
同步返回，`data` 中每项对应一张生成的图片：
```json
{
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/seedream/xxx.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": {
    "generated_images": 1,
    "output_tokens": 15908,
    "total_tokens": 15908
  }
}
```
- `data` (array) — 生成的图片。
- `data[].url` (string) — 有效期 24 小时的图片链接，`response_format` 为 `url` 时返回。
- `data[].b64_json` (string) — `response_format` 为 `b64_json` 时返回的 Base64 内容。
- `data[].size` (string) — 该张图片的实际像素尺寸，如 `2048x2048`。
- `data[].output_format` (string) — 该张图片的文件格式。图层固定为 `png`，底图跟随请求中的 `output_format`。
- `data[].z_index` (integer) — 图层叠放顺序，仅图层拆分时返回。底图固定为 `0`，图层从 `1` 开始递增。
- `data[].name` (string) — 图层名称，仅图层拆分时返回。
- `data[].description` (string) — 图层描述，仅图层拆分时返回，比 `name` 更详细。
- `data[].bounding_box` (object) — 图层在输出底图坐标系中所占区域，仅图层返回，含 `absolute` 与 `normalized` 两套坐标。
- `data[].error` (object) — 单图失败信息，仅组图场景中某一张失败而其余成功时出现。
- `created` (integer) — 完成时间，Unix 秒。
- `usage` (object) — 用量信息，网关按此结算。含 `generated_images`、`input_images`、`output_tokens`、`total_tokens`。
> **Note:** 
> 生成是同步的，请求会阻塞到全部图片出完。1K 通常几十秒内返回，2K 更久，客户端超时建议设到 5 分钟以上。链接 24 小时有效，需要长期保存请及时转存。
## 错误码
| HTTP | 含义 |
|---|---|
| 400 | 请求参数错误：模型未知、`size` 超出模型范围、参考图过多、该模型不支持的字段 |
| 401 | Token 缺失或无效，type 为 authentication_error |
| 429 | 触发限流 |
常见 400 原因：`model` 写了缩写；`size` 超出 `1024x1024` 到 `4096x4096` 或比例越界；`n` 大于 1；参考图超过 10 张；图层拆分未传图或传了多张；透明背景用于文生图。
更多状态码与重试建议见[错误码与限流](../../../support/errors.html)，常见报错的排查步骤见[常见问题](../../../support/faq.html)。
## 支持的模型列表
以下图像模型均可通过本接口提交任务，清单只列各厂商最新一代，实际可用范围以你的账号分组为准：
:::models image
两个型号的参数完全相同，差别只在速度与成本：
| 型号 | 定位 |
|---|---|
| `doubao-seedream-5-0-pro-260628` | 画质与文字准确度最好，适合成片交付 |
| `doubao-seedream-5-0-flash-260915` | 出图快、成本低，适合批量与草稿 |
> **Note:** 完整模型目录（含价格、分辨率上限）可读取 `GET https://ark.oairoute.com/api/pricing`。
## 计费
总价 = 输出图单价 + 参考图加价 × max(0, 参考图张数 − 1)。
输出图按实际像素面积分档，第 1 张参考图免费，第 2 张起每张加收固定单价。任务失败自动全额退款。图层拆分时每个输出图层单独计费。
具体价格见[模型价格与分组接口](../../model-pricing.html)。
## 使用示例
### 内联 Base64 输出
需要把结果直接存进数据库或内网服务时，用 `b64_json` 避免二次下载。
### 组图
`sequential_image_generation: "auto"` 一次最多返回 4 张同主题图片。某一张失败时该数组项只带 `error`，其余照常返回，`usage.generated_images` 只计成功的张数。
### 图层还原
拆分得到的图层按下标与 `url`、`size`、`output_format` 对应，`z_index` 为 `0` 的是底图。
1. 按 `z_index` 从小到大叠放
2. 绝对坐标换算为 `x=left`、`y=top`、`w=right−left`、`h=bottom−top`
3. 任意 W×H 画布用归一化值除以 1000 再乘画布尺寸
**文生图{Text to image}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedream-5-0-flash-260915",
  "prompt": "赛博朋克风格的城市夜景，雨后湿滑的街道反射霓虹灯",
  "size": "2K"
}'
```
**文生图{Text to image}::Python**
```
import requests
url = "https://ark.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "doubao-seedream-5-0-flash-260915",
    "prompt": "赛博朋克风格的城市夜景，雨后湿滑的街道反射霓虹灯",
    "size": "2K",
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**文生图{Text to image}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-flash-260915",
    prompt: "赛博朋克风格的城市夜景，雨后湿滑的街道反射霓虹灯",
    size: "2K",
  }),
});
console.log(await res.json());
```
**单图编辑{Single-image edit}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedream-5-0-pro-260628",
  "prompt": "给这张图加上暖色夕阳光",
  "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_1.png",
  "size": "2K"
}'
```
**单图编辑{Single-image edit}::Python**
```
import requests
url = "https://ark.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "给这张图加上暖色夕阳光",
    "image": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_1.png",
    "size": "2K",
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**单图编辑{Single-image edit}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro-260628",
    prompt: "给这张图加上暖色夕阳光",
    image: "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_1.png",
    size: "2K",
  }),
});
console.log(await res.json());
```
**多图融合{Multi-image fusion}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedream-5-0-pro-260628",
  "prompt": "把两个人都放进同一场景，影棚灯光",
  "image": [
    "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_1.png",
    "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_2.png"
  ],
  "size": "2K"
}'
```
**多图融合{Multi-image fusion}::Python**
```
import requests
url = "https://ark.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "把两个人都放进同一场景，影棚灯光",
    "image": [
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_1.png",
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_2.png",
    ],
    "size": "2K",
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**多图融合{Multi-image fusion}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro-260628",
    prompt: "把两个人都放进同一场景，影棚灯光",
    image: [
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_1.png",
      "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimages_2.png",
    ],
    size: "2K",
  }),
});
console.log(await res.json());
```
**内联 Base64{Inline Base64}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedream-5-0-flash-260915",
  "prompt": "极简风格的纸鹤海报，米白背景",
  "size": "1K",
  "response_format": "b64_json"
}'
```
**内联 Base64{Inline Base64}::Python**
```
import requests
url = "https://ark.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "doubao-seedream-5-0-flash-260915",
    "prompt": "极简风格的纸鹤海报，米白背景",
    "size": "1K",
    "response_format": "b64_json",
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**内联 Base64{Inline Base64}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-flash-260915",
    prompt: "极简风格的纸鹤海报，米白背景",
    size: "1K",
    response_format: "b64_json",
  }),
});
console.log(await res.json());
```
**生成组图{Image group}::cURL**
```
curl --request POST \
  --url 'https://ark.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_ARK_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "doubao-seedream-5-0-pro-260628",
  "prompt": "女孩抱着奶牛玩偶坐过山车，早晨、正午与傍晚",
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": { "max_images": 4 },
  "size": "2K",
  "watermark": false
}'
```
**生成组图{Image group}::Python**
```
import requests
url = "https://ark.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
}
payload = {
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "女孩抱着奶牛玩偶坐过山车，早晨、正午与傍晚",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": {"max_images": 4},
    "size": "2K",
    "watermark": False,
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**生成组图{Image group}::JavaScript**
```
const res = await fetch("https://ark.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ARK_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro-260628",
    prompt: "女孩抱着奶牛玩偶坐过山车，早晨、正午与傍晚",
    sequential_image_generation: "auto",
    sequential_image_generation_options: { max_images: 4 },
    size: "2K",
    watermark: false,
  }),
});
console.log(await res.json());
```
**200 文生图{Text to image}**
```
{
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/seedream/xxx.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": {
    "generated_images": 1,
    "output_tokens": 15908,
    "total_tokens": 15908
  }
}
```
**200 单图编辑{Single-image edit}**
```
{
  "data": [
    {
      "url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/seedream/edit-xxx.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": {
    "generated_images": 1,
    "input_images": 1,
    "output_tokens": 15908,
    "total_tokens": 15908
  }
}
```
**200 内联 Base64{Inline Base64}**
```
{
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
      "size": "1024x1024",
      "output_format": "jpeg"
    }
  ],
  "created": 1757469067,
  "usage": {
    "generated_images": 1,
    "output_tokens": 4096,
    "total_tokens": 4096
  }
}
```