# Doubao Seedream 5.0 Pro 图片生成与编辑

> Seedream 5.0 Pro 普通模式的公共参数、参考图限制、尺寸规格、输出格式与调用示例

Seedream 5.0 Pro 通过 `POST /api/v3/images/generations` 同步生成或编辑图片，兼容火山方舟图片生成 API 的请求与响应契约。文生图不传 `image`；单图编辑传一个字符串；多参考图融合传字符串数组。普通模式每次返回一张基础图。

<Warning>
本页介绍普通生成与编辑模式。请省略 `layer_decomposition`，或显式设为 `false`。如需一张基础图和多个透明图层，请参阅[图层拆分](/api-capabilities/seedream/layer-decomposition)。
</Warning>

## 创建图片

`POST /api/v3/images/generations`

<CodeGroup>

```bash 文生图（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "一只戴宇航头盔的柴犬坐在月球表面，远处是地球，写实摄影",
    "size": "2K",
    "response_format": "url",
    "watermark": true
  }'
```

```python 文生图（Python · Ark SDK）
import os
from volcenginesdkarkruntime import Ark

client = Ark(
    base_url="https://api.looprouter.com/api/v3",
    api_key=os.environ["LOOPROUTER_API_KEY"],
)

result = client.images.generate(
    model="doubao-seedream-5-0-pro-260628",
    prompt="一只戴宇航头盔的柴犬坐在月球表面，远处是地球，写实摄影",
    size="2K",
    output_format="jpeg",
    response_format="url",
    watermark=True,
)

print(result.data[0].url)
```

```bash 单图编辑（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "把外套改成酒红色，其余内容保持不变",
    "image": "https://example.com/images/portrait.jpg",
    "size": "2K"
  }'
```

```bash 多参考图融合（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "让图1中的人物穿上图2中的服装，并采用图3的室内光线",
    "image": [
      "https://example.com/images/person.jpg",
      "https://example.com/images/outfit.jpg",
      "https://example.com/images/lighting.jpg"
    ],
    "size": "2K"
  }'
```

```bash 透明背景 PNG 编辑（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "将主体改成蓝色陶瓷材质，保持透明背景",
    "image": "https://example.com/images/object-with-alpha.png",
    "output_format": "png",
    "background": "transparent",
    "size": "1.5K"
  }'
```

```bash b64_json 返回（cURL）
curl -X POST "https://api.looprouter.com/api/v3/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedream-5-0-pro-260628",
    "prompt": "极简产品海报，米白背景，柔和棚拍光线",
    "size": "1500x1000",
    "output_format": "png",
    "response_format": "b64_json",
    "optimize_prompt_options": { "mode": "fast" },
    "watermark": false
  }'
```

</CodeGroup>

<Note>
Python 示例使用 Ark SDK，并将 `base_url` 设置为 `https://api.looprouter.com/api/v3`。API Key 始终从 `LOOPROUTER_API_KEY` 环境变量读取。
</Note>

## 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | — | 固定为 `doubao-seedream-5-0-pro-260628` |
| `prompt` | string | 是 | — | 非空提示词，支持模型提供的多语种输入 |
| `image` | string / string[] | 否 | — | 非空参考图 URL 或 Data URI；普通模式最多 10 张，数组项也不能为空 |
| `size` | string | 否 | `2K` | `1K` / `1.5K` / `2K`，或显式 `宽x高` |
| `optimize_prompt_options.mode` | string | 否 | `standard` | `standard` 或 `fast` |
| `output_format` | string | 否 | `jpeg` | `jpeg` 或 `png` |
| `background` | string | 否 | `opaque` | `opaque` 或满足条件时使用 `transparent` |
| `response_format` | string | 否 | `url` | `url` 或 `b64_json` |
| `layer_decomposition` | boolean | 否 | `false` | 普通模式省略或设为 `false` |
| `watermark` | boolean | 否 | `true` | 是否添加“AI 生成”水印 |
| `stream` | boolean | 否 | `false` | 仅接受 `false`，调用仍为同步；`true` 会返回参数错误 |

`size` 档位中的 `K` 匹配不区分大小写（例如 `2K` 与 `2k` 均可接受）；建议使用表中的规范写法。`optimize_prompt_options` 是对象，其中可选的 `mode` 仅接受 `standard` 或 `fast`。

### 参考图限制

`image` 可使用可公开访问的 URL，或 `data:image/<format>;base64,<data>` 形式的 Data URI。单张参考图必须满足：

- 格式为 **jpeg（也接受 jpg 别名）、png、webp、bmp、tiff（也接受 tif 别名）、gif、heic 或 heif**；
- 宽高比位于 **[1/16, 16]**；
- 宽和高均 **大于 14 px**；
- 文件大小 **不超过 30 MB**；
- 总像素位于 **[196, 36,000,000]**；
- 普通模式最多输入 **10 张**参考图。

## 尺寸规格

`size` 支持分辨率档位或显式宽高，两种写法不可混用。

### 分辨率档位

可选 `1K`、`1.5K`、`2K`，默认 `2K`。模型会结合提示词和参考图确定最终宽高。

### 显式 `宽x高`

例如 `2048x1024`。宽乘以高及宽高比必须同时满足：

- 总像素位于 **[921600, 4624220]**；
- 宽高比位于 **[1/16, 16]**。

| 示例 | 是否有效 | 说明 |
| --- | --- | --- |
| `2048x1024` | 是 | 2,097,152 像素，宽高比为 2 |
| `1500x1000` | 是 | 1,500,000 像素，宽高比为 1.5 |
| `512x512` | 否 | 262,144 像素，低于最小值 |

<Note>
显式宽高不要求按 8、16 或 64 的倍数对齐，只需满足总像素与宽高比范围。
</Note>

## 输出格式与透明背景

`output_format` 决定图片编码格式，`background` 决定背景行为。透明背景只在符合条件的单图编辑中可用。

| `output_format` | `background` | 支持情况 |
| --- | --- | --- |
| `jpeg` | `opaque` | 支持，默认组合 |
| `png` | `opaque` | 支持 |
| `png` | `transparent` | 条件支持：必须是只输入一张图片的编辑请求 |
| `jpeg` | `transparent` | 不支持 |

使用 `background: "transparent"` 时，必须传入且只传入一张图片，并将 `output_format` 设为 `png`。不满足条件的组合会返回参数错误。

## 返回方式

| `response_format` | `data[]` 字段 | 说明 |
| --- | --- | --- |
| `url` | `url` | 默认值；下载链接在图片生成后 **24 小时**内有效 |
| `b64_json` | `b64_json` | 直接返回 Base64 图片数据，不依赖临时链接 |

`response_format` 只改变图片数据的交付方式，不改变 `output_format`。例如 PNG 可通过 URL 返回，也可通过 `b64_json` 返回。

## 成功响应

普通模式的 `data` 包含一项。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 实际请求模型 |
| `created` | integer | Unix 时间戳（秒） |
| `data` | object[] | 普通模式包含一张基础图 |
| `usage` | object | 输入图片数、输出图片数和 token 统计 |

`data[]` 的字段如下：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `url` | string | `response_format: "url"` 时返回，**24 小时**内有效 |
| `b64_json` | string | `response_format: "b64_json"` 时返回 |
| `size` | string | 实际输出尺寸，格式为 `宽x高` |
| `output_format` | string | 实际输出格式，`jpeg` 或 `png` |

`usage` 包含：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `input_images` | integer | 输入参考图数量 |
| `generated_images` | integer | 生成的输出图片数量 |
| `output_tokens` | integer | 各输出图片像素总和除以 256 后取整 |
| `total_tokens` | integer | 此接口中与 `output_tokens` 一致 |

```json 成功响应
{
  "model": "doubao-seedream-5-0-pro-260628",
  "created": 1785125529,
  "data": [
    {
      "url": "https://example.com/generated/output.jpeg",
      "size": "2048x2048",
      "output_format": "jpeg"
    }
  ],
  "usage": {
    "input_images": 0,
    "generated_images": 1,
    "output_tokens": 16384,
    "total_tokens": 16384
  }
}
```

## 错误响应

失败时返回包含 `error.code` 与 `error.message` 的 JSON。`param`、`type` 仅在有明确值时出现。错误对象中的 `code` 存在且不为 `null`，或 `message` / `type` 非空时，接口都会将其识别为失败，而不会把该响应当作成功图片结果。

```json 参数错误
{
  "error": {
    "code": "InvalidParameter",
    "message": "The parameter `size` is invalid."
  }
}
```

| HTTP 状态码 | 常见错误 | 说明 |
| --- | --- | --- |
| 400 | `InvalidParameter` | 缺少必填参数、尺寸越界、图片不符合限制或参数组合无效 |
| 401 | `AuthenticationError` | API Key 缺失或无效 |
| 429 | `RateLimitExceeded` | 请求频率超出当前可用额度 |
| 5xx | 以 `error.code` 为准 | 服务端错误，错误码与消息按实际失败原因返回 |

<Warning>
Seedream 5.0 Pro 不接受 `n`、`sequential_image_generation`、`sequential_image_generation_options` 或 `tools`。接口仅支持同步调用：`stream: true` 会收到参数错误；省略 `stream` 或传 `false` 均保持同步。
</Warning>

## 相关文档

<CardGroup cols={2}>
  <Card title="交互编辑" icon="crosshairs" href="/api-capabilities/seedream/interactive-editing">
    标注图、点坐标与框坐标示例
  </Card>
  <Card title="图层拆分" icon="layer-group" href="/api-capabilities/seedream/layer-decomposition">
    自动拆分、定向拆分与图层响应字段
  </Card>
  <Card title="能力概览" icon="circle-info" href="/api-capabilities/seedream/overview">
    查看支持能力与模式差异
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/seedream/create-image">
    在线查看请求与响应结构
  </Card>
</CardGroup>