> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedream

> Seedream 5.0 Pro 和 Seedream 5.0 Flash 图片生成 API。

参数及使用方式与火山方舟图片生成 API 一致，详细参数说明请参考：[火山方舟图片生成 API](https://docs.volcengine.com/docs/ark/image-generation-api?lang=zh)。

## 一、概述

本文档说明 Seedream 5.0 Pro 和 Seedream 5.0 Flash 图片生成接口的调用方式、请求参数、响应结构和计费规则。

本接口为同步接口：请求返回时即包含生成结果，不需要轮询。两个模型共用同一个接口，请求体中的 `model` 决定使用的模型；支持文生图、图生图、多图融合和图层拆分。

### 1.1 接口地址

| 操作 | 接口 |
| - | - |
| 生成图片 | `POST /v3/bytedance-cn/api/v3/images/generations` |

其中 `{api_domain}` 为平台为您提供的 API 域名，完整地址为 `https://{api_domain}` 加上表中路径。

### 1.2 鉴权

所有请求都需要携带平台 API Key，并指定 JSON 内容类型：

```http theme={null}
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
```

### 1.3 支持模型

| 模型 | 支持场景 | 说明 |
| - | - | - |
| `doubao-seedream-5-0-pro-260628` | 文生图、单图生图、多图融合、图层拆分 | 生成质量更高；按输出图片像素分档计费，额外参考图单独计费；支持 `optimize_prompt_options.mode` 取 `fast` |
| `doubao-seedream-5-0-flash-260915` | 文生图、单图生图、多图融合、图层拆分 | 生成速度更快；每张输出图片单价相同，输入图片不计费 |

两个模型的接口、鉴权、请求与响应结构相同，差异在于 `model` 取值和计费方式。两者都不支持组图生成和流式输出。

## 二、调用图片生成

参数说明：[火山方舟图片生成 API](https://docs.volcengine.com/docs/ark/image-generation-api?lang=zh)

### 2.1 请求示例：文生图

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/bytedance-cn/api/v3/images/generations' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "一只戴着红色围巾的金毛犬，在雪山湖边的自然光下，电影感摄影",
    "size": "2K",
    "response_format": "url",
    "watermark": false
  }'
```

### 2.2 请求示例：多图融合

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/bytedance-cn/api/v3/images/generations' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedream-5-0-flash-260915",
    "prompt": "将图1中的人物换上图2中的服装，放在城市夜景中，保持人物特征一致",
    "image": [
      "https://example.com/person.png",
      "https://example.com/outfit.png"
    ],
    "size": "2048x1152",
    "response_format": "url"
  }'
```

`image` 传单个字符串即为单图生图；传数组即为多图融合，最多 10 张。

### 2.3 请求示例：图层拆分

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/bytedance-cn/api/v3/images/generations' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "把人物、背景和标题文字拆成独立图层",
    "image": "https://example.com/poster.png",
    "layer_decomposition": true,
    "size": "auto"
  }'
```

图层拆分把单张输入图拆成一张底图和最多 16 个可独立编辑的图层。`prompt` 可选，不传时模型自动识别图片中的主要元素并拆分。

### 2.4 请求字段

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | `doubao-seedream-5-0-pro-260628` 或 `doubao-seedream-5-0-flash-260915` |
| `prompt` | string | 图片生成时必填；图层拆分时可选 | 支持中文、英文及多种其他语言；建议中文不超过 300 字、英文不超过 600 词 |
| `image` | string / string\[] | 图层拆分时必填 | 参考图 URL 或 Base64 Data URL；限制见 2.6 |
| `layer_decomposition` | boolean | 否 | 默认 `false`；`true` 时开启图层拆分 |
| `size` | string | 否 | 图片生成默认 `2K`，可选 `1K`、`1.5K`、`2K` 或 `宽x高`；图层拆分默认 `auto`，可选 `1K`、`1.5K`、`2K`、`auto`；规则见 2.5 |
| `output_format` | string | 否 | `jpeg`（默认）或 `png`；图层拆分时只控制底图格式，图层始终为 `png` |
| `background` | string | 否 | `opaque`（默认）或 `transparent`；限制见 2.5 |
| `optimize_prompt_options.mode` | string | 否 | `standard`（默认）；Seedream 5.0 Pro 还支持 `fast`，生成更快、效果略低 |
| `response_format` | string | 否 | `url`（默认）或 `b64_json` |
| `watermark` | boolean | 否 | 默认 `true`，在图片右下角添加「AI 生成」水印 |

### 2.5 尺寸与组合规则

`size` 的取值：

| 场景 | 可选值 | 说明 |
| - | - | - |
| 图片生成 | `1K`、`1.5K`、`2K`（默认） | 由模型结合提示词中的宽高比描述决定实际尺寸，例如 `2K` + 3:2 输出 `2496x1664` |
| 图片生成 | `宽x高` | 总像素在 921,600（1280x720）到 4,624,220 之间，宽高比在 1/16 到 16 之间 |
| 图层拆分 | `1K`、`1.5K`、`2K`、`auto`（默认） | 只支持档位，不支持 `宽x高`；底图分辨率等于 `size`，各图层分辨率接近 `size` 并保持其在原图中的宽高比 |

图层拆分 `auto` 模式下，原始尺寸在 921,600 到 4,624,220 像素之间的底图和图层按原尺寸输出，小于 1K 的按 1K 输出，大于 2K 的按 2K 输出。

组合约束：

* 图层拆分时 `image` 必填且只能传一张，传多张返回错误。
* 图层拆分为全有或全无：任一图层生成失败，整个请求失败。
* `background` 为 `transparent` 时只支持图生图，且只能输入一张带透明通道的图片；输出默认为 `png`，同时指定 `output_format` 为 `jpeg` 会返回错误。
* 不支持 `stream`、`sequential_image_generation` 和 `sequential_image_generation_options`，传入任一字段返回 400。

### 2.6 输入图片限制

| 场景 | 格式 | 大小 | 其他 |
| - | - | - | - |
| 图片生成 | jpeg、png、webp、bmp、tiff、gif、heic、heif | ≤ 30 MB | 最多 10 张；宽高比 1/16 到 16；宽、高均大于 14 px；总像素 196 到 36,000,000 |
| 图层拆分 | png、jpeg | ≤ 30 MB | 只能 1 张；宽高比 1/16 到 16；总像素 262,144（512x512）到 36,000,000 |

图片 URL 必须可公开访问。Base64 格式为 `data:image/<图片格式>;base64,<Base64 编码>`，图片格式需小写，如 `data:image/png;base64,...`。

### 2.7 响应说明

成功响应示例：

```json theme={null}
{
  "created": 1793952000,
  "model": "doubao-seedream-5-0-pro-260628",
  "data": [
    {
      "url": "https://example.com/generated-image.jpeg",
      "size": "2496x1664",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "generated_images": 1,
    "input_images": 0,
    "output_tokens": 16224,
    "total_tokens": 16224
  }
}
```

| 字段 | 类型 | 说明 |
| - | - | - |
| `created` | integer | 创建时间，Unix 时间戳（秒） |
| `model` | string | 本次请求的模型 |
| `data[].url` | string | `response_format` 为 `url` 时返回；24 小时内有效，请及时下载 |
| `data[].b64_json` | string | `response_format` 为 `b64_json` 时返回 |
| `data[].size` | string | 实际输出尺寸，格式 `宽x高`；Seedream 5.0 Pro 按它确定价格档位 |
| `data[].output_format` | string | `jpeg` 或 `png` |
| `data[].z_index` | integer | 仅图层拆分返回；底图为 `0`，图层从 `1` 递增，数值越大越靠上 |
| `data[].name` / `data[].description` | string | 仅图层拆分返回；图层名称和描述 |
| `data[].bounding_box` | object | 仅图层返回（底图不返回）；`absolute` 为底图坐标系下的像素坐标 `[left, top, right, bottom]`，`normalized` 为换算到 0–1000 的坐标 |
| `usage.generated_images` | integer | 成功生成的图片数 |
| `usage.input_images` | integer | 输入图片数 |
| `usage.output_tokens` / `usage.total_tokens` | integer | 输出图片的 token 数，不参与计费 |

图片生成返回一个 `data` 项；图层拆分返回多个 `data` 项（一张底图加多个图层），按 `z_index` 从小到大叠放即可还原。

## 三、计费说明

```text theme={null}
请求费用 = Σ（每张成功输出图片的单价） + 额外参考图费用（仅 Seedream 5.0 Pro）
```

两个模型都按请求**实际生成结果**计费，请求返回时完成计费：

| 项目 | Seedream 5.0 Pro | Seedream 5.0 Flash |
| - | - | - |
| 计费数量 | 每张成功输出图片计 1 张；图层拆分时底图和每个图层各计 1 张 | 同左 |
| 价格档位 | 每张输出图片按其 `data[].size` 的像素分档：≤ 2,610,000 像素与 > 2,610,000 像素两档；图层拆分使用单独的图层价格 | 不分档，所有输出图片单价相同 |
| 输入图片 | 第 1 张免费，从第 2 张起每张计费 | 不计费 |
| 失败请求 | 未生成图片的请求不产生费用 | 同左 |

同一次图层拆分请求的底图和各图层像素不同，可能分别落在两个档位，账单按各档位张数分别累计。图片生成时，`1K`、`1.5K` 档的输出通常在 2,610,000 像素以内，`2K` 档的输出通常超过 2,610,000 像素；以响应中的 `data[].size` 为准。

### 3.1 计费与 usage 字段对照

| 字段 | 是否参与计费 | 说明 |
| - | - | - |
| `data[].size` | 是（Seedream 5.0 Pro） | 决定每张输出图片的价格档位 |
| `usage.generated_images` | 是 | 成功输出图片数，与计费张数一致 |
| `usage.input_images` | 是（Seedream 5.0 Pro） | 输入图片数；计费的额外参考图张数为该值减 1 |
| `usage.output_tokens` / `usage.total_tokens` | 否 | 仅供参考 |

具体单价以您所使用服务的价格页面为准。

## 四、常见错误

| HTTP | 场景 | 处理建议 |
| - | - | - |
| 400 | JSON 格式错误；`model` 不在支持列表中；传入 `stream: true` 或组图字段 | 根据 `metadata.details` 修正请求 |
| 400 | API Key 缺失 | 检查 `Authorization: Bearer <API_KEY>` 请求头 |
| 400 | 参数取值不合法，如 `size` 超出范围、图片无法读取 | 根据 `error.message` 修正请求，错误体见 4.1 |
| 403 | API Key 无效；余额或预算不足 | 检查 API Key，或充值、调整预算后重试 |
| 429 | 请求频率超过限制 | 降低请求频率，并使用退避重试 |
| 500 | 服务端错误 | 使用 `trace_id` 联系技术支持 |

### 4.1 错误响应结构

请求格式、鉴权、余额和模型校验失败时，错误体如下，`metadata.trace_id` 可用于排查：

```json theme={null}
{
  "code": 400,
  "reason": "INVALID_REQUEST_BODY",
  "message": "invalid request body",
  "metadata": {
    "details": "body.model must be one of: doubao-seedream-5-0-flash-260915, doubao-seedream-5-0-pro-260628",
    "trace_id": "platform-trace-id"
  }
}
```

参数取值不合法、图片无法读取或内容审核未通过时，错误体如下，`error.code` 与 `error.message` 说明具体原因：

```json theme={null}
{
  "error": {
    "code": "InvalidParameter",
    "message": "The parameter `size` specified in the request are not valid: image area must be at least 921600 pixels. Request id: ...",
    "param": "size",
    "type": "BadRequest"
  }
}
```

两种错误体都表示请求未生成图片，不产生费用。

## 五、使用建议

1. 收到成功响应后立即下载 `data[].url`，地址 24 小时后失效。
2. 需要控制 Seedream 5.0 Pro 成本时，可使用 `1K` 或 `1.5K` 档，输出通常落在 2,610,000 像素以内的低档。
3. 图层拆分时只传一张图片，`size` 使用档位或 `auto`，不要传 `宽x高`。
4. 不要传 `stream`、`sequential_image_generation`、`sequential_image_generation_options`，否则返回 400。
5. 生成较慢时可设置较长的客户端超时（建议 120 秒以上）；超时不代表请求一定未成功，请结合业务侧幂等控制决定是否重试。
6. 对时延敏感的业务，可使用 Seedream 5.0 Flash，或使用 Seedream 5.0 Pro 的 `optimize_prompt_options.mode: fast`。

## 六、Python 调用示例

以下示例使用标准 `requests` 库演示文生图。图生图、多图融合或图层拆分只需在请求体中加入 `image`、`layer_decomposition` 等字段。

```python theme={null}
import os

import requests


api_domain = os.environ["API_DOMAIN"]
api_key = os.environ["PLATFORM_API_KEY"]

payload = {
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "一只戴着红色围巾的金毛犬，在雪山湖边的自然光下，电影感摄影",
    "size": "2K",
    "response_format": "url",
}

response = requests.post(
    f"https://{api_domain}/v3/bytedance-cn/api/v3/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=180,
)
response.raise_for_status()
result = response.json()
for item in result["data"]:
    print(item["size"], item["url"])
print(result["usage"])
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.