# Seedream 图片

> Ark 原生格式的同步图片生成，含参考图编辑和 5 Pro 图层拆分。

Base URL：`https://platform.sgt.site/volcengine`

本文中的接口路径均相对于此 Base URL；完整请求地址由二者拼接。

| 方法 | 路径 | 用途与返回 |
| --- | --- | --- |
| POST | `/api/v3/images/generations` | 文生图、参考图生成、组图或图层拆分；同步 JSON 或 SSE 图片结果 |

提交示例均使用 `Authorization: Bearer YOUR_VIRTUAL_KEY` 与 `Content-Type: application/json`。“原生”指与厂商官方 API 相同的请求和响应格式：把官方 Base URL 换成本页 Base URL、官方密钥换成平台虚拟密钥即可调用。平台只开放本文列出的模型、操作和字段，官方的账号管理、回调等功能不在其中。

<a id="native-seedream-section-1"></a>

## 1.1 路径与模型

`POST /api/v3/images/generations` 直接返回图片结果；启用 `stream` 时按 SSE 读取结果。本接口不创建供调用方查询的异步任务。

| 模型 | 请求中的 model |
| --- | --- |
| Seedream 5 Lite | `doubao-seedream-5-0-lite-260128` |
| Seedream 5 Pro | `doubao-seedream-5-0-pro-260628` |
| Seedream 4.0 | `doubao-seedream-4-0-250828` |
| Seedream 4.5 | `doubao-seedream-4-5-251128` |
| Seedream 5 Lite 保留名称 | `doubao-seedream-5-0-260128` |

实际可调用项由 `GET https://platform.sgt.site/v1/models` 或 `GET /api/v3/models` 返回的目录决定。自动发现客户端也可使用相对于本页 Base URL 的 `GET /models` 或 `GET /v1/models`，均支持尾斜杠，返回同一授权目录而不限于火山渠道模型。这两个别名是平台兼容扩展，不是火山官方列表 API；使用平台虚拟密钥，空目录返回 HTTP 200、`data: []`，读取不调用上游生成或扣费。生成路径仍为下文的原生路径。

<a id="native-seedream-section-2"></a>

## 1.2 常用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 必填，使用平台原生目录名称 |
| `prompt` | string | 普通生成必需；图层拆分可省略 |
| `image` | string / string[] | 参考图 URL、受支持的图片 Data URI；多图用数组 |
| `size` | string | 分辨率档位或 `宽x高`，如 `2K`、`2048x2048`；各模型取值见 1.6 |
| `n` | integer | 只能省略或为 1；组图用下方 `max_images`，不能用 `n=2` 请求两张 |
| `sequential_image_generation` | string | `disabled` 或 `auto`；组图使用 `auto`，`n` 只能省略或为 1 |
| `sequential_image_generation_options.max_images` | integer | 组图最大输出数，1–15，省略按 15；参考图和输出总数最多 15，实际预冻结上界还会扣除参考图数量 |
| `response_format` | string | `url`（默认，链接 24 小时内有效）或 `b64_json` |
| `watermark` | boolean | 官方默认 `true`，会在右下角加“AI 生成”水印；不需要时显式传 `false` |
| `output_format` | string | `jpeg`（默认）或 `png`，Seedream 5.0 pro / lite 支持；透明输出选择 PNG |
| `stream` | boolean | 默认 `false`；Seedream 5.0 lite / 4.5 / 4.0 可开启，开启后按 SSE 事件读取 |
| `background` | string | `opaque`（默认）或 `transparent`，仅 Seedream 5.0 pro；透明背景只支持输入 1 张带透明通道的图片，且输出须为 PNG |
| `layer_decomposition` | boolean | Seedream 5 Pro 图层拆分，见下节 |
| `optimize_prompt_options.mode` | string | `standard` 或 `fast`；支持范围见 1.7，省略时保留模型默认行为 |
| `tools` | object[] | Seedream 5 Lite 可传 `[{"type":"web_search"}]` 启用搜索；有独立搜索费用，见 1.7 |

各模型可用的分辨率档位、像素范围和参考图要求见 1.6。`size` 按原值传给模型，调用方须确保尺寸在该型号允许的范围内；平台不会自动放大小图或把像素尺寸换算为比例。像素写法使用小写 `x`，不要写乘号 `×`。

官方 Ark Python SDK（回归报文版本 `volcengine-python-sdk==5.0.52`）会将未设置的部分可选参数发送为 `null`。对本页已列出的 Seedream 型号，顶层 `image`、`output_format`、`background`、`seed`、`guidance_scale`、`optimize_prompt`、`optimize_prompt_options`、`sequential_image_generation`、`sequential_image_generation_options` 和 `tools` 的 `null` 按省略处理；`stream`、`watermark` 和 `layer_decomposition` 的 `null` 沿用未指定行为。普通单图调用无需手动清除这些 SDK 默认值。此规则不新增 `seed`、`guidance_scale` 或 `optimize_prompt` 的模型能力承诺；有效非空参数仍以本页字段表为准。

兼容仅限已知顶层可选字段。显式 `false` 与 `0` 保留原值并按字段规则校验，例如 `watermark:false` 保留，而 `n:0`、`max_images:0` 仍被拒绝。嵌套 `max_images:null`、`optimize_prompt_options.mode:null` 和 `tools:[null]` 仍返回 400。普通转发省略这些未指定字段，透传转发保留 SDK 原报文并使用相同的校验语义；平台 `/media/v1` 与 APIMart 的严格 `null` 契约不变。

组图要求模型已配置按张价格，按合法最大输出数预冻结；不具备对应计费配置时在发送前返回明确错误。值不为 `null` 的组图选项只能与 `auto` 一起使用；0、负数、非整数、`null` 或超过 15 的 `max_images` 返回 400。Seedream 5 Pro 不接受值不为 `null` 的顺序组图字段或 `stream:true`；图层拆分也不能与组图组合。字段校验和计费上界同时适用于普通与透传请求，不因透传开关改变。

非流式完整响应按成功产物数或官方 `usage.generated_images` 结算，错误项不算成功图片。流式 `image_generation.partial_succeeded` 表示单个成功产物，`image_generation.completed` 是整个请求的汇总事件，不能把每个 completed 当一张图。以汇总 `usage.generated_images` 或完整成功产物证据为准；完整空结果可为零张，部分失败只计已确认产物。断流、矛盾用量或缺少完整证据时保留预留并进入账务待核对，不按预冻结张数结算。保存响应关联 request_id 供管理员核查，不自动重新请求以补齐证据。

组图请求示例（同一接口；`stream:false` 返回普通 JSON，改为 `true` 读取 SSE）：

```bash
curl -X POST 'https://platform.sgt.site/volcengine/api/v3/images/generations' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "model": "doubao-seedream-5-0-lite-260128",
  "prompt": "生成两张独立图片：一张白色陶瓷杯，一张蓝色陶瓷杯，纯白背景",
  "size": "2K",
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {"max_images": 2},
  "stream": false,
  "response_format": "url"
}
JSON
```

该请求预留最多两张的费用；最大张数不是保证张数，以最终计量证据为准。

<a id="native-seedream-section-3"></a>

## 1.3 文生图

```bash
BASE_URL="https://platform.sgt.site/volcengine"
curl -X POST "$BASE_URL/api/v3/images/generations" \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "model": "doubao-seedream-5-0-lite-260128",
  "prompt": "生成一张产品展示图：白色陶瓷杯置于浅灰色桌面，柔和自然光",
  "size": "2K",
  "n": 1,
  "response_format": "url",
  "watermark": false,
  "stream": false
}
JSON
```

同步成功响应示例：

```json
{
  "model": "doubao-seedream-5-0-lite-260128",
  "created": 1790553600,
  "data": [
    {
      "url": "https://media.example.com/generated-image.png",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1
  }
}
```

字段以模型返回为准。遍历 `data`，处理每项输出及可能的错误；`response_format=b64_json` 时读取 `data[].b64_json`，按照实际图片格式保存字节。

<a id="native-seedream-section-4"></a>

## 1.4 参考图生成/编辑

仍使用图片生成接口，在请求中加入 `image`；不要将 Seedream 图生图改成 multipart 的 `https://platform.sgt.site/v1/images/edits`。

```bash
curl -X POST 'https://platform.sgt.site/volcengine/api/v3/images/generations' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "model": "doubao-seedream-5-0-pro-260628",
  "prompt": "保留参考图中的杯子外形，将背景改成木质餐桌",
  "image": [
    "https://media.example.com/source.png"
  ],
  "size": "2K",
  "n": 1,
  "response_format": "url",
  "watermark": false,
  "output_format": "png"
}
JSON
```

<a id="native-seedream-section-5"></a>

## 1.5 Seedream 5 Pro 图层拆分

路径与普通图片生成相同，仅 Seedream 5.0 pro 支持 `layer_decomposition`，请求须满足下方图层拆分限制。

```bash
curl -X POST 'https://platform.sgt.site/volcengine/api/v3/images/generations' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://media.example.com/poster.png",
  "layer_decomposition": true,
  "size": "2K",
  "n": 1,
  "response_format": "url",
  "output_format": "png",
  "stream": false
}
JSON
```

使用要求：

- 必须提供恰好一张输入图；`image` 可以是字符串或只有一个元素的数组。
- `size` 可省略或取 `auto/1K/1.5K/2K`；`n` 只能省略或为 1。
- 不支持流式、顺序组图参数或 `tools`。输出图层数量由模型决定，最多按底图加 16 层处理。
- 输入图只支持 PNG、JPEG，不超过 30 MB，总像素在 512×512（262144）到 6000×6000（3600 万）之间，宽高比 [1/16, 16]；透明背景需输入带透明通道的 PNG 并输出 PNG。
- 响应仍是 `data[]`，每项包含 `z_index`、`name`、`description`、`bounding_box`、`size` 和图片 URL/Base64；`z_index=0` 为底图，图层从 1 开始，越大越靠上。图层始终为 PNG，`output_format` 只影响底图。任一图层失败则整体报错。
- 图层按实际输出计费，不能直接用 `n=1` 推断只收一张普通图片的费用。

<a id="native-seedream-section-6"></a>

## 1.6 官方接口与输入限制

官方接口：`POST https://ark.cn-beijing.volces.com/api/v3/images/generations`，平台接口 `POST /api/v3/images/generations`，请求体相同。使用火山方舟 SDK 时把 `base_url` 设为本页 Base URL 加 `/api/v3`，即 `https://platform.sgt.site/volcengine/api/v3`、API Key 换成平台虚拟密钥。

**参考图 `image`（图片生成）：**

| 项 | 要求 |
| --- | --- |
| 来源 | 可公网访问的 URL，或 `data:image/<格式>;base64,<数据>`（格式小写） |
| 格式 | jpeg、png、webp、bmp、tiff、gif、heic、heif |
| 大小 | 单张不超过 30 MB |
| 宽高 | 宽、高均大于 14 px；总像素（宽×高）在 196 到 6000×6000（3600 万）之间 |
| 宽高比 | [1/16, 16] |
| 数量 | Seedream 5.0 pro 最多 10 张；5.0 lite / 4.5 / 4.0 最多 14 张 |

**输出尺寸 `size`：**两种写法二选一，不可混用。写档位时可在提示词中描述画面比例，由模型决定具体像素；写 `宽x高` 时须同时满足总像素和宽高比范围（总像素指宽×高的乘积，不是单边长度）。

| 模型 | 档位写法 | `宽x高` 总像素范围 | 默认值 |
| --- | --- | --- | --- |
| Seedream 5.0 pro | `1K`、`1.5K`、`2K` | 1280×720（921600）到 2048×2048×1.1025（4624220） | `2K` |
| Seedream 5.0 lite | `2K`、`3K`、`4K` | 2560×1440（3686400）到 4096×4096（16777216） | `2048x2048` |
| Seedream 4.5 | `2K`、`4K` | 2560×1440（3686400）到 4096×4096（16777216） | `2048x2048` |
| Seedream 4.0 | `1K`、`2K`、`4K` | 1280×720（921600）到 4096×4096（16777216） | `2048x2048` |

所有模型的 `宽x高` 宽高比都须在 [1/16, 16] 内。例如 Seedream 4.5 写 `1500x1500` 无效（总像素 225 万低于下限），写 `3750x1250` 有效。

常用档位对应的实际像素（官方参考值）：

| 档位 | 1:1 | 4:3 | 16:9 | 9:16 | 21:9 |
| --- | --- | --- | --- | --- | --- |
| 1K（4.0） | 1024x1024 | 1152x864 | 1280x720 | 720x1280 | 1512x648 |
| 1K（5.0 pro） | 1024x1024 | 1152x864 | 1424x800 | 800x1424 | 1568x672 |
| 1.5K（5.0 pro） | 1536x1536 | 1792x1344 | 2048x1152 | 1152x2048 | 2352x1008 |
| 2K | 2048x2048 | 2304x1728 | 2848x1600 | 1600x2848 | 3136x1344 |
| 3K（5.0 lite） | 3072x3072 | 3456x2592 | 4096x2304 | 2304x4096 | 4704x2016 |
| 4K | 4096x4096 | 4704x3520 | 5504x3040 | 3040x5504 | 6240x2656 |

5.0 pro 的 2K 档略有不同：4:3 为 2368x1776，16:9 为 2816x1584。

**其他官方规则：**

- 提示词建议中文不超过 300 字、英文不超过 600 词，过长容易忽略细节。
- 返回的图片 URL 24 小时内有效，请及时下载保存。
- 图层拆分模式下 `size` 可取 `1K`、`1.5K`、`2K` 或 `auto`（默认，按原图尺寸输出，小于 1K 按 1K、大于 2K 按 2K）。

<a id="native-seedream-h-d3775afe"></a>

## 1.7 提示词优化与搜索

提示词优化在同一图片请求中添加 `optimize_prompt_options`。只接受 `mode`，不接受其他子字段或 `null`；不传该对象时不会强行指定优化模式。

| 模型 | `standard` | `fast` | `tools.web_search` |
| --- | --- | --- | --- |
| Seedream 4.0 | 支持 | 支持 | 不支持 |
| Seedream 4.5 | 支持 | 不支持 | 不支持 |
| Seedream 5 Lite（含保留名称） | 支持 | 不支持 | 支持，需有效搜索价格与预留配置 |
| Seedream 5 Pro | 支持 | 支持 | 不支持 |

例如 `"optimize_prompt_options":{"mode":"standard"}`。显式的 `watermark:false`、`stream:false` 等值会按原值传递，不能把省略与 `false` 当作同一种输入。

搜索工具的请求格式固定为 `"tools":[{"type":"web_search"}]`，至多一个工具；不接受其他工具类型、重复工具或额外工具字段。`tools:[]` 表示不使用工具，`tools:null` 无效。搜索仅对 Seedream 5 Lite 开放，可以与该型号支持的组图及流式生成组合。

```bash
curl -X POST 'https://platform.sgt.site/volcengine/api/v3/images/generations' \
  -H 'Authorization: Bearer YOUR_VIRTUAL_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "model": "doubao-seedream-5-0-lite-260128",
  "prompt": "搜索广州塔的外观资料，生成一张简洁的旅行海报",
  "size": "2K",
  "optimize_prompt_options": {"mode": "standard"},
  "tools": [{"type": "web_search"}],
  "response_format": "url",
  "stream": false
}
JSON
```

搜索请求的完整响应在图片用量外提供搜索次数，例如：

```json
{
  "model": "doubao-seedream-5-0-lite-260128",
  "created": 1792022400,
  "data": [{"url": "https://media.example.com/travel-poster.png", "size": "2048x2048"}],
  "usage": {"generated_images": 1, "tool_usage": {"web_search": 2}}
}
```

`usage.tool_usage.web_search` 是实际搜索调用次数，不是“是否启用了工具”。示例按一张图片和两次搜索分别计费；若明确返回 0 次搜索，则搜索费用为零。即使最终没有成功图片，只要有完整可信的搜索用量，已发生的搜索仍计费。

发送前会预留图片费用及一份搜索费用估计。这份估计不是官方次数上限，也不是传给模型的限制；模型实际搜索次数可能更多。搜索费用使用本次请求冻结的有效价格，实际次数超过预留估计、缺少 `tool_usage.web_search`、值无效或互相矛盾时，保留资金并进入待核对，不把缺失量默认记成 0 或 1。管理员尚未配置搜索价格或预留估计时，请求会在发送前被拒绝；不要通过透传绕过。

<a id="native-seedream-h-7577cb78"></a>

## 1.8 流式消费与异常处理

调用支持流式的型号时，将请求中的 `stream` 改成 `true`，在上面的 curl 中加 `-N` 避免客户端缓冲。读取 SSE `data:` 中的 JSON，按其 `type` 处理；下面是两张组图中一张成功、一张失败的示意事件：

```text
data: {"type":"image_generation.partial_succeeded","image_index":0,"url":"https://media.example.com/one.png","size":"2048x2048"}

data: {"type":"image_generation.partial_failed","image_index":1,"error":{"code":"ImageGenerationFailed","message":"image generation failed"}}

data: {"type":"image_generation.completed","usage":{"generated_images":1,"tool_usage":{"web_search":2}}}
```

`partial_succeeded` 包含单张成功产物，`partial_failed` 只表示该张失败，`completed` 提供整次请求汇总。它们不是三张图片，也不能把 `completed` 再加一张。搜索的重复累计汇总不累加；完整一致的最终次数才是计费证据。未启用搜索的响应不要求出现 `tool_usage.web_search`。

流式响应已经开始后，HTTP 200 不能保证生成或计量完整。连接提前结束、终态汇总缺失、图片数与可信证据冲突时，应保存已有产物和关联 request_id，查询调用记录并由管理员核对；不要为了补齐输出自动重新 POST。此同步接口没有异步任务查询端点。

| 情况 | 处理 |
| --- | --- |
| 401 或 403 | 检查虚拟密钥、模型授权及预算权限 |
| 400，参数错误 | 检查型号是否支持组图、流式、优化模式及搜索；修正后再提交 |
| 计费配置不可用 | 请管理员配置该模型的图片价格及所需工具价格，不要重复调用尝试 |
| 有部分产物或 `partial_failed` | 逐项保存成功图片，按完整汇总确定最终实际数量 |
| 5xx、断连或缺少完整用量 | 可能已有生成或费用，保存关联 ID，先核对结果，不自动重复提交 |

原生能力依据：[火山图片生成 API](https://docs.volcengine.com/docs/ark/image-generation-api?lang=zh)。平台支持范围以本页型号及字段约束为准。