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

# 通过 Comfy Router 使用 Seedream 5.5 261028

> 通过 Comfy Router 调用 byteplus/seedream-5-5-261028：端点、请求结构以及 Router 返回的响应。

`byteplus/seedream-5-5-261028` 的 API 参考，由 Comfy Router 从 BytePlus 提供。

**输入：** 文本、图像 · **输出：** 图像

## 快速开始

在 [你的 Comfy 工作区](https://platform.comfy.org/profile/api-keys?onboarding=router) 中创建密钥，并将其导出为 `COMFY_API_KEY`。Python 和 TypeScript 代码片段使用 Comfy SDK（`pip install comfy-sdk` 和 `npm install @comfyorg/sdk`）；cURL 代码片段则通过原始 HTTP 进行相同的调用。

**模型 ID：** `byteplus/seedream-5-5-261028`

**端点：** `POST https://api.comfy.org/v2/models/byteplus/seedream-5-5-261028`

> [tab] 等待结果
>
> ```python Python theme={null}
> from comfy_sdk import Comfy
>
> # 从环境中读取 COMFY_API_KEY。
> # SDK 会自动创建幂等键，并在自动重试时复用它。
> with Comfy() as client:
>     result = client.models.run(
>         "byteplus/seedream-5-5-261028",
>         {
>             "prompt": "A red fox trotting through a snowy pine forest, cinematic lighting",
>             "response_format": "url",
>             "watermark": False,
>         },
>     )
>
> print(result)
> ```
>
> ```typescript TypeScript theme={null}
> import { comfy } from "@comfyorg/sdk";
>
> // 从环境中读取 COMFY_API_KEY。
> // SDK 会自动创建幂等键，并在自动重试时复用它。
> const { data } = await comfy.models.run("byteplus/seedream-5-5-261028", {
>   prompt: "A red fox trotting through a snowy pine forest, cinematic lighting",
>   response_format: "url",
>   watermark: false,
> });
>
> console.log(data);
> ```
>
> ```bash cURL theme={null}
> curl https://api.comfy.org/v2/models/byteplus/seedream-5-5-261028 \
>   -H "X-API-Key: $COMFY_API_KEY" \
>   -H "Idempotency-Key: $(uuidgen)" \
>   -H "Content-Type: application/json" \
>   -d "{\"prompt\": \"A red fox trotting through a snowy pine forest, cinematic lighting\", \"response_format\": \"url\", \"watermark\": false}"
> ```

> [tab] 加入队列并稍后收集
>
> 相同的请求体，发送到 `POST https://api.comfy.org/v2/models/byteplus/seedream-5-5-261028/requests`。只要运行被接纳，Router 就会立即返回 `201` 和 `request_id`，结果准备就绪后即可收集，无论来自当前进程还是另一个进程。[队列投递](https://docs.comfy.org/zh/development/comfy-router/queue.md) 会介绍状态、取消和收集的完整流程。
>
> ```python Python theme={null}
> import asyncio
> from comfy_sdk import AsyncComfy
>
> # 从环境中读取 COMFY_API_KEY。
> # 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。
> async def main():
>     async with AsyncComfy() as client:
>         handle = await client.models.submit(
>             "byteplus/seedream-5-5-261028",
>             {
>                 "prompt": "A red fox trotting through a snowy pine forest, cinematic lighting",
>                 "response_format": "url",
>                 "watermark": False,
>             },
>         )
>         print("request_id:", handle.request_id)  # 有了模型 ID，另一个进程所需的信息就齐了
>
>         # 轮询直到请求完成，并等待服务器指定的 Retry-After 时间。
>         async for update in handle.iter_events():
>             print(update.status, update.queue_position)
>
>         # 提供商自己的载荷，与 models.run() 返回的值相同。
>         # 失败或已取消的请求会在此处抛出类型化的 Router 错误。
>         result = await handle.get()
>
>     print(result)
>
> asyncio.run(main())
> ```
>
> ```typescript TypeScript theme={null}
> import { comfy } from "@comfyorg/sdk";
>
> // 从环境中读取 COMFY_API_KEY。
> // 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。
> const handle = await comfy.models.submit("byteplus/seedream-5-5-261028", {
>   prompt: "A red fox trotting through a snowy pine forest, cinematic lighting",
>   response_format: "url",
>   watermark: false,
> });
> console.log("requestId:", handle.requestId); // 有了模型 ID，另一个进程所需的信息就齐了
>
> // 轮询直到请求完成，并等待服务器指定的 Retry-After 时间。
> for await (const update of handle.events()) {
>   console.log(update.status, update.queuePosition);
> }
>
> // 与 models.run() 返回的结果相同。失败或已取消的请求会在此处被拒绝。
> const result = await handle.get();
>
> console.log(result.data);
> ```
>
> ```bash cURL theme={null}
> # 1. 提交。Router 会返回 201，并附带 request_id、status_url、response_url 和 cancel_url。
> curl https://api.comfy.org/v2/models/byteplus/seedream-5-5-261028/requests \
>   -H "X-API-Key: $COMFY_API_KEY" \
>   -H "Idempotency-Key: $(uuidgen)" \
>   -H "Content-Type: application/json" \
>   -d "{\"prompt\": \"A red fox trotting through a snowy pine forest, cinematic lighting\", \"response_format\": \"url\", \"watermark\": false}"
>
> # 2. 轮询直到状态为 COMPLETED，并等待每次响应指定的 Retry-After 秒数。
> REQUEST_ID="<request_id from the 201 body>"
> curl -i https://api.comfy.org/v2/models/byteplus/seedream-5-5-261028/requests/$REQUEST_ID/status \
>   -H "X-API-Key: $COMFY_API_KEY"
>
> # 3. 收集。返回 200 及模型原生输出；仍在运行时返回 202 及状态响应体。
> curl https://api.comfy.org/v2/models/byteplus/seedream-5-5-261028/requests/$REQUEST_ID \
>   -H "X-API-Key: $COMFY_API_KEY"
> ```

## Schema

### 输入

**background** `string`

控制生成的图像是否具有透明背景（alpha 通道）。由 seedream-5.0-pro、5.0-flash 以及自身 schema 中记录该参数的较新 Seedream 模型支持。
auto: 模型根据提示词和 output\_format 决定。当 output\_format 为 jpeg 时，输出始终为不透明。
transparent: 输出带透明背景的 RGBA 图像。output\_format 为 jpeg 时返回错误。
opaque: 输出带不透明背景的 RGB 图像。seedream-5.0-pro 的默认值。
seedream-5.0-pro 仅在图生图时支持透明输出，且需要一张带 alpha 通道的 png 输入图像。
图层分离场景不支持该参数：在启用 layer\_decomposition 时传入它会返回错误。

可选值：`auto`、`transparent`、`opaque`

**guidance\_scale** `number`

控制输出图像与输入提示词的对齐程度。范围 \[1, 10]。数值越高，对提示词的遵循越强。seedream-5.0-pro、5.0-lite、4.5 和 4.0 不支持该参数。

范围：`1` 到 `10`

格式：`float`

**image** `string | string[]`

要编辑的一张或多张图像，以可访问的 URL 或带 data-URI 前缀的 Base64 数据形式提供。除参考图上限不同外，与共享的 Seedream 字段完全一致：本模型的上限为 10，而不是 14。

**layer\_decomposition** `boolean` (default: false)

控制是否启用图层分离。仅 seedream-5.0-pro、5.0-flash 和 5.5 支持该参数。
true: 图层分离模式。模型将单张输入图像分解为一张基础图像和多个图层（最多 16 个；在 seedream-5.5 上最多 99 个），并返回每个生成图层的位置和内容信息，包括堆叠顺序（z\_index）、边界框（bounding\_box）、名称（name）和描述（description）。
false: 标准图像生成模式；不执行图层分离。
关于图层分离模式的说明：仅支持单张输入图像（传入多张图像会返回错误）；只要任一图层生成失败，整个请求就会失败，不支持部分成功；最多返回 17 张图像（1 张基础图像 + 16 个图层）。seedream-5.5 最多返回 layer\_decomposition\_options.max\_images 张图像（1 张基础图像 + 最多 99 个图层）。传入 sequential\_image\_generation、sequential\_image\_generation\_options、tools 和 stream 会返回错误。

**layer\_decomposition\_options** `object`

图层分离模式的选项。仅 seedream-5.5 支持该参数，且仅在 layer\_decomposition 为 true 时生效。

**layer\_decomposition\_options.max\_images** `integer` (default: 30)

本次请求返回的图像总数上限，即基础图像与各图层之和。范围：\[2, 100]。当提示词未说明如何拆分图像时，模型会根据 max\_images 和输入图像的复杂度来规划图层；数值越大，通常图层划分越精细。

范围：`2` 到 `100`

**model** `string`

模型标识符。支持的模型：seedream-4-0-250828、seedream-4-5-251128、seedream-5-0-260128、seedream-5-0-pro-260628、seedream-5-0-flash-260915 和 seedream-5-5-261028。以 v1 直接调用 POST /proxy/byteplus/api/v3/images/generations 时必须提供它：代理会拒绝任何其他值，也会拒绝省略它的请求，并返回 400。它不在本 schema 的 `required` 列表中，因为 Comfy Router 会从 /v2/models/byteplus/\{model} 的 `{model}` 路径段填充它，所以 Router 调用方会省略它。

**optimize\_prompt\_options** `object`

提示词优化功能的配置。仅 seedream-5.0-pro/5.0-lite/4.5/5.5（仅支持 standard 模式；seedream-5.5 在 fast 模式下会返回错误）和 seedream-4.0 支持该参数。

**optimize\_prompt\_options.mode** `string` (default: "standard")

设置提示词优化功能的模式。standard = 质量更高，生成时间更长。fast = 速度更快，但质量较为一般。

可选值：`standard`、`fast`

**output\_format** `string` (default: "jpeg")

指定输出图像的格式。仅 seedream-5.0-pro、5.0-flash、5.0-lite 和 5.5 支持该参数。seedream-5.5 默认为 png。在图层分离场景中，output\_format 只控制基础图像的格式；每个图层始终以 png 输出。

可选值：`png`、`jpeg`

**prompt** `string`

用于图像生成或变换的文本描述。
在图层分离场景中为可选（即在启用 layer\_decomposition 的 seedream-5.0-pro、5.0-flash 或 5.5 上）：如果提供了提示词，模型会按照提示词意图识别并分离你指定的元素；如果未提供提示词，模型会自动检测图像中的所有主要元素，并将它们分离为独立图层。

**response\_format** `string` (default: "url")

指定响应中返回的已生成图像的格式

可选值：`url`、`b64_json`

**seed** `integer` (default: -1)

用于控制图像生成随机性的随机种子。范围：\[-1, 2147483647]。如果未指定，将自动生成一个种子。要复现相同的输出，请使用相同的种子值。

范围：`-1` 到 `2147483647`

**sequential\_image\_generation** `string`

控制是否禁用批处理生成功能。该参数仅在 seedream-5.0-lite、4.5 和 4.0 上受支持（seedream-5.0-pro、5.0-flash 和 5.5 不支持）。有效值：
auto: 在自动模式下，模型会根据用户提示词自动决定是否返回多张图像以及其中包含多少张图像。
disabled: 禁用批处理生成功能。模型将只生成一张图像。

可选值：`auto`、`disabled`

**sequential\_image\_generation\_options** `object`

仅 seedream-5.0-lite、4.5 和 4.0 支持此参数（seedream-5.0-pro、5.0-flash 或 5.5 不支持）。
批处理图像生成功能的配置。仅当 sequential\_image\_generation 设置为 auto 时，此参数才生效。

**sequential\_image\_generation\_options.max\_images** `integer` (default: 15)

指定本次请求中要生成的最大图像数量。输入参考图像数量 + 生成图像数量 ≤ 15。

范围：`1` 至 `15`

**size** `string`

"seedream-4-0-250828"：设置生成图像的规格。有两种方法可用，但不能同时使用。
方法 1 | 指定分辨率。可选值：1K、2K、4K
方法 2 | 以像素为单位指定宽度和高度。默认：2048x2048，总像素：\[1024x1024, 4096x4096]，宽高比：\[1/16, 16]
"seedream-4-5-251128"：有两种方法可用。
方法 1 | 指定分辨率。可选值：2K、4K
方法 2 | 以像素为单位指定宽度和高度。默认：2048x2048，总像素：\[2560x1440, 4096x4096]，宽高比：\[1/16, 16]
"seedream-5-0-260128"：有两种方法可用。
方法 1 | 指定分辨率。可选值：2K、3K
方法 2 | 以像素为单位指定宽度和高度。默认：2048x2048，总像素：\[2560x1440, \~3072x3072]，宽高比：\[1/16, 16]
"seedream-5-0-pro-260628"：有两种方法可用（不能同时使用）。
方法 1 | 指定分辨率，并在提示词中描述图像的宽高比、形状或用途；由模型决定最终尺寸。可选值：1K、2K
方法 2 | 以像素为单位指定宽度和高度。默认：1024x1024，总像素：\[1024x1024 (1048576), 2048x2048 (4194304)]，宽高比：\[1/16, 16]
"seedream-5-0-flash-260915"：有两种方法可用（不能同时使用）。
方法 1 | 指定分辨率，并在提示词中描述图像的宽高比、形状或用途；由模型决定最终尺寸。可选值：1K、1.5K、2K。默认：2K
方法 2 | 以像素为单位指定宽度和高度。总像素：\[1280x720 (921600), 2048x2048x1.1025 (4624220)]，宽高比：\[1/16, 16]
"seedream-5-5-261028"：有两种方法可用（不能同时使用）。
方法 1 | 指定分辨率。可选值：1K、1.5K、2K。默认：2K
方法 2 | 以像素为单位指定宽度和高度。总像素：\[1280x720 (921600), 2048x2048x1.1025 (4624220)]，宽高比：\[1/16, 16]
"seedream-5-0-pro-260628"、"seedream-5-0-flash-260915" 和 "seedream-5-5-261028" 启用 layer\_decomposition 时：仅支持分辨率级别的方法。可选值：1K、1.5K、2K、auto。默认：auto。
基础图像按指定分辨率输出，并采用原始输入图像的宽高比；每个图层输出时接近指定分辨率，并保持其在原始图像中的宽高比。
auto: 输出基于输入图像的尺寸和宽高比。\[1280x720, \~2048x2048] 范围内的输入按原始输入尺寸输出；小于 1K 的输入按 1K 输出；大于 2K 的输入按 2K 输出。

**stream** `boolean` (default: false)

Comfy Router 会将显式提供的 stream 标志置为 false，因为它会捕获完整的 JSON 结果。在 v1 代理上，此字段控制是否启用流式输出模式。仅 seedream-5.0-lite、4.5 和 4.0 支持此参数（seedream-5.0-pro、5.0-flash 或 5.5 不支持）。false = 所有输出图像一次性返回。true = 每张输出图像在生成后立即返回。

**watermark** `boolean` (default: true)

指定是否为生成图像添加水印。false = 不添加水印，true = 添加带有 'AI generated' 标签的水印

根据 Router 在 `GET /v2/models/byteplus/seedream-5-5-261028/openapi.json` 提供的 schema 生成，该文档与它在请求到达提供商之前用于校验调用的文档相同。

### 输出

**created** `integer`

Unix 时间戳（单位为秒），表示该请求的创建时间

**data** `object[]`

包含生成的图像的相关信息。
在图层分离场景中，数组的第一个元素是基础图像（z\_index=0），其后的元素是各图层，按 z\_index 递增的顺序排列。

**data\[].b64\_json** `string`

Base64 编码的图像数据（当 response\_format 为 "b64\_json" 时）

**data\[].background** `string`

图像实际具有的背景类型：transparent 或 opaque。在图层分离场景中，基础图像始终为 opaque，每个图层均为 transparent。仅 seedream-5.5 返回该字段。

**data\[].bounding\_box** `object`

当前图层在基础图像中所占区域的边界框信息。仅图层返回该字段；基础图像覆盖整个画布，不返回 bounding\_box。仅在 layer\_decomposition 为 true 时返回。

**data\[].bounding\_box.absolute** `integer[]`

图层边界框的绝对像素坐标，位于输出基础图像的坐标系中，左上角为 (0, 0)。坐标格式：\[left, top, right, bottom]。

**data\[].bounding\_box.normalized** `integer[]`

图层边界框按千分位量化（归一化）后的坐标，基于基础图像尺寸按比例映射到 \[0, 1000] 的离散整数区间，最大截断为 1000。坐标格式：\[left, top, right, bottom]。

**data\[].description** `string`

当前分离元素的详细描述，相比 name 提供更丰富的图层特征（如颜色、状态、材质）。仅图层返回该字段；基础图像不返回。仅在 layer\_decomposition 为 true 时返回。

**data\[].name** `string`

当前分离元素的名称/标签，由模型根据所分离主体的特征自动生成。仅图层返回该字段；基础图像不返回。仅在 layer\_decomposition 为 true 时返回。

**data\[].output\_format** `string`

输出图像的文件格式。仅 seedream-5.0-pro 和 5.5 支持该字段。

**data\[].size** `string`

图像的宽度和高度（单位为像素），格式为 \<width>x\<height>。仅 seedream-5.0-pro、5.0-lite、5.5、4.5 和 4.0 支持该参数。

**data\[].url** `string (uri)`

用于下载图像的 URL（当 response\_format 为 "url" 时）

格式：`uri`

**data\[].z\_index** `integer`

图层的堆叠顺序，从下到上递增：0 为最底部的图层（基础图像）；数值越大层级越高。可使用它按正确的堆叠顺序将各图层重新合成为完整图像。仅在 layer\_decomposition 为 true 时返回。

**error** `object`

错误信息（如有）

**error.code** `string`

上游 ModelArk 错误码。SensitiveContentDetected、InputTextSensitiveContentDetected、InputImageSensitiveContentDetected、InputVideoSensitiveContentDetected、InputAudioSensitiveContentDetected、OutputTextSensitiveContentDetected、OutputImageSensitiveContentDetected、OutputVideoSensitiveContentDetected 和 OutputAudioSensitiveContentDetected 表示因内容策略而拒绝。同一错误族可能带有以点分隔的原因，例如 InputImageSensitiveContentDetected.PrivacyInformation、OutputVideoSensitiveContentDetected.PolicyViolation 或 OutputImageSensitiveContentDetected.DeepFake。这是一个开放字符串，而非枚举：其他错误码描述验证失败和提供商故障。Router 会在 HTTP 400 错误响应和 HTTP 200 失败任务响应中识别策略错误族，但不会覆盖传输层故障。

**error.message** `string`

报错信息

**model** `string`

用于该请求的模型 ID

**usage** `object`

**usage.generated\_images** `integer`

模型生成的图像数量

**usage.input\_images** `integer`

输入到模型的图像数量。仅 seedream-5.0-pro 和 5.5 支持该字段。

**usage.output\_tokens** `integer`

模型生成图片所消耗的 token 数量。

**usage.total\_tokens** `integer`

该请求消耗的 token 总数。

## 示例

### 输入

```json theme={null}
{
  "prompt": "A red fox trotting through a snowy pine forest, cinematic lighting",
  "response_format": "url",
  "watermark": false
}
```

### 输出

```json theme={null}
{
  "created": 1767225600,
  "data": [
    {
      "size": "1024x1024",
      "url": "https://example.invalid/byteplus/seedream-4-0-250828/generated.png"
    }
  ],
  "model": "seedream-5-5-261028",
  "usage": {
    "generated_images": 1
  }
}
```

## 发布前须知

SDK 会生成 `Idempotency-Key` 并在自动重试中复用它。手动重试时，请复用原始 key。Router 最长可保持连接 10 分钟。

请求失败时，Router 会发送 `X-Comfy-Error-Type` 响应头说明原因。`422` 表示 Router 在调用提供商之前就拒绝了输入，`413` 表示请求体超出了 Router 可接受的大小。已生成的资源请及时下载，因为[结果 URL 会过期](https://docs.comfy.org/zh/development/comfy-router/reference.md#结果资产)。

上文任何字段描述中提到的尺寸限制，都是提供商对该字段自身的限定，引自提供商的规范。Router 会对整个请求体另行设置上限，base64 编码的媒体内容也计入其中：参见[请求体大小](https://docs.comfy.org/zh/development/comfy-router/limitations.md)。

本页记录的是通过 Comfy Router 调用的某一个合作伙伴模型。同一个 `comfy-sdk` / `@comfyorg/sdk` 包还提供第二个客户端，用于在 Comfy Cloud 上运行完整的 ComfyUI 工作流图：`Comfy(api_key=...)` / `new Comfy({ apiKey })`，并带有 `client.workflows`、`client.assets` 和 `client.jobs`。请参阅 [Comfy SDKs](https://docs.comfy.org/zh/development/api-development/sdks.md)。

> [card] [请求头](https://docs.comfy.org/zh/development/comfy-router/headers.md)
>
> 身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。

> [card] [使用 Router API](https://docs.comfy.org/zh/development/comfy-router/api.md)
>
> 模型发现、验证错误、重试与计费。

> [card] [限制](https://docs.comfy.org/zh/development/comfy-router/limitations.md)
>
> Router 目前不支持的功能，以及替代方案。


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