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

# Seedream

参数及使用方式已对齐官方，详细参数可直接参考官方文档。

## 一、概述

Seedream 图片生成 API 使用 OpenAI 风格的图片生成请求格式，支持文生图、图生图和图片编辑。四个模型使用同一个接口，客户端只需要在请求 body 的 model 字段中选择模型。

### 支持的模型

| 客户端模型 ID                       | 模型                | 输出方式    |
| ------------------------------ | ----------------- | ------- |
| `seedream-4-0-250828`          | Seedream 4.0      | 单图或组图   |
| `seedream-4-5-251128`          | Seedream 4.5      | 单图或组图   |
| `seedream-5-0-260128`          | Seedream 5.0 Lite | 单图或组图   |
| `dola-seedream-5-0-pro-260628` | Seedream 5.0 Pro  | 单图或图层拆分 |

## 二、接口和鉴权

```http theme={null}
POST https://{api_domain}/v3/bytedance/api/v3/images/generations
```

请求头：

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

`{api_domain}` 使用您所在平台的 API 域名。请求必须使用 POST，body 必须是 JSON。

## 三、请求参数

### 3.1 通用参数

<ParamField body="model" type="string" required={true}>
  使用上表中的模型 ID。
</ParamField>

<ParamField body="prompt" type="string" required={true}>
  图片描述，支持中文和英文。
</ParamField>

<ParamField body="image" type="string / string[]">
  参考图 URL 或 Base64 Data URL。可以传一张图片，也可以传数组。具体数量和图片限制以所选模型的限制为准。
</ParamField>

<ParamField body="size" type="string">
  使用模型支持的分辨率档位或 `宽x高`。未传时使用模型默认值。
</ParamField>

<ParamField body="response_format" type="string">
  `url` 或 `b64_json`，默认 `url`。
</ParamField>

<ParamField body="output_format" type="string">
  仅 Seedream 5.0 Lite 和 5.0 Pro 支持：`jpeg` 或 `png`。Seedream 4.0 和 4.5 固定输出 JPEG；传入 `output_format` 会被拒绝。
</ParamField>

<ParamField body="watermark" type="boolean">
  是否添加 AI 生成水印。
</ParamField>

<ParamField body="stream" type="boolean">
  图片接口不支持流式输出，请勿传 `true`。
</ParamField>

### 3.2 模型专属参数

| 参数                                    | 可使用的模型           | 说明                                                                                                  |
| ------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------- |
| `sequential_image_generation`         | 4.0、4.5、5.0 Lite | 组图生成开关。需要组图时按对应模型的上游协议填写；不使用组图时省略。                                                                  |
| `sequential_image_generation_options` | 4.0、4.5、5.0 Lite | 组图生成选项，与 `sequential_image_generation` 一起使用。                                                        |
| `size` 的 1K、1.5K、2K 档位                | 5.0 Pro          | Pro 支持这些档位，也支持明确的 `宽x高`。Pro 不支持组图参数。图层拆分场景仅支持档位（含 auto），并通过 `layer_decomposition: true` 开启（详见模型限制）。 |

Seedream 5.0 Pro 不支持 `sequential_image_generation` 和 `sequential_image_generation_options`；传入任一字段都会被拒绝。其它模型的专属参数不要发送给 Pro。

### 3.3 文生图示例

下面的请求以 Seedream 5.0 Pro 为例。四个模型共用相同接口；使用 Seedream 4.0 或 4.5 时必须删除 `output_format`，使用 Seedream 5.0 Lite/Pro 时才可传入该字段：

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

### 3.4 图生图示例

`image` 可以是单个 URL、单个 Base64 Data URL 或字符串数组：

```json theme={null}
{
  "model": "seedream-4-5-251128",
  "prompt": "将参考图中的人物和服装放在统一的城市夜景中，保持人物特征一致",
  "image": [
    "https://example.com/person.png",
    "https://example.com/outfit.png"
  ],
  "size": "2560x1440",
  "response_format": "url"
}
```

### 3.5 组图示例（仅 4.0、4.5、5.0 Lite）

组图参数属于前三个模型，示例：

```json theme={null}
{
  "model": "seedream-5-0-260128",
  "prompt": "生成三张风格统一的四季海报",
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {
    "max_images": 3
  },
  "response_format": "url"
}
```

请以所选模型的上游协议确认组图参数的可用取值和数量限制。

## 四、响应

成功响应示例：

```json theme={null}
{
  "created": 1786000000,
  "model": "seedream-4-5-251128",
  "data": [
    {
      "url": "https://example.com/generated-image.jpeg",
      "size": "2560x1440",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "generated_images": 1,
    "input_images": 0
  }
}
```

* `response_format=url` 时返回 `data[].url`；`response_format=b64_json` 时返回 `data[].b64_json`。
* Seedream 4.0、4.5、5.0 Lite 在组图模式下可以返回多个 `data` 项。
* Seedream 5.0 Pro 在图片生成场景返回一个 `data` 项；开启图层拆分时返回多个 `data` 项（一张底图 + 多个图层），每项额外包含图层堆叠顺序 `z_index`（底图为 0）、名称 `name`、描述 `description` 和边界框 `bounding_box`（含 absolute / normalized 坐标，底图不返回该字段）。
* `model` 返回本次请求使用的客户端模型 ID。
* 图片 URL 的有效期由平台和上游服务决定，请在返回后及时下载并保存图片。

## 五、模型限制

### Seedream 4.0 / 4.5 / 5.0 Lite

* 支持文生图、图生图和组图生成。
* 组图使用 `sequential_image_generation` 及其 options 字段。
* 输入图片数量、图片大小、分辨率和宽高比以对应模型的上游文档为准。Seedream 4.0 和 4.5 固定输出 JPEG，不支持请求参数 `output_format`；Seedream 5.0 Lite 支持 `jpeg` 和 `png`。

### Seedream 5.0 Pro

* 支持文生图、单图生图和多图融合。
* 图片生成场景下返回一张成功图片。开启图层拆分（`layer_decomposition: true`）时返回一张底图和多个图层（最多 16 个图层），此时 `data` 为多项。不支持组图生成（`sequential_image_generation`）。
* 不支持 `sequential_image_generation` 和 `sequential_image_generation_options`。
* `size` 可使用 1K、1.5K、2K 或明确的 `宽x高`。
* 明确宽高时，宽高比和总像素必须满足模型限制；输出图片的实际尺寸以响应中的 `data[].size` 为准。
* 支持图层拆分：设置 `layer_decomposition: true` 时，将单张输入图拆解为一张底图和最多 16 个可独立编辑的图层（每个图层为带 alpha 通道的 PNG）。此场景 `image` 必填且只能传一张，传多张报错。图层拆分为全有或全无：任一图层失败则整个请求失败，不支持部分成功。
* 图层拆分的 `size` 规则：底图分辨率等于 `size`；各图层分辨率接近 `size`，但每个图层保持其在原图中对应区域的宽高比，因此各图层实际像素不同。这意味着同一次请求的输出图片可能落在不同的像素价格档位。`size` 可选 1K、1.5K、2K、auto，默认 auto。

## 六、计费和用量

* 4.0、4.5 和 5.0 Lite 按成功生成的图片数量计费；组图生成时按实际成功输出数量计算。
* 5.0 Pro 按成功输出图片计费；多图输入时，首张参考图免费，额外参考图单独计量；输出尺寸不同会对应不同价格档位。开启图层拆分时，底图和每个图层都算一张成功输出图片，各自按其 `data[].size` 的像素落入对应价格档位分别计费（例如底图为高像素档、部分图层为低像素档），最终账单为各档位数量之和。
* 用量单位为“张”或 item。

## 七、错误排查

| 场景            | 建议                                      |
| ------------- | --------------------------------------- |
| 模型不支持         | 检查 `model` 是否与上表完全一致。                   |
| 缺少 prompt     | body 必须包含非空提示词。                         |
| 图片无法读取        | 检查 URL 的可访问性、格式、大小和像素限制。                |
| `stream=true` | 图片接口不支持流式输出，删除该字段或设为 `false`。           |
| Pro 传入组图字段    | 删除两个 `sequential_image_generation*` 字段。 |
| size 无效       | 使用所选模型支持的档位或符合限制的 `宽x高`。                |