ComfyPilotComfyPilot
文档 / 开发 / 使用 Comfy Router 调用 Seedream 5.0 Pro 260628

使用 Comfy Router 调用 Seedream 5.0 Pro 260628

通过 Comfy Router 调用 byteplus/seedream-5-0-pro-260628：端点、请求格式以及 Router 返回的响应。

开发 code 更新于 2026-10-11

查看官方原文

使用 Comfy Router 调用 Seedream 5.0 Pro 260628

通过 Comfy Router 调用 byteplus/seedream-5-0-pro-260628：端点、请求格式以及 Router 返回的响应。

byteplus/seedream-5-0-pro-260628 的 API 参考，由 Comfy Router 从 BytePlus 提供。

输入： 文本, 图像 · 输出： 图像

快速开始

在 你的 Comfy 工作区 中创建一个密钥，并将其导出为 COMFY_API_KEY。Python 和 TypeScript 代码片段使用 Comfy SDK（pip install comfy-sdk 和 npm install @comfyorg/sdk）；cURL 代码片段则是通过原始 HTTP 发起的同一调用。

模型 ID： byteplus/seedream-5-0-pro-260628

端点： POST https://api.comfy.org/v2/models/byteplus/seedream-5-0-pro-260628

[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-0-pro-260628", { "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-0-pro-260628", { 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-0-pro-260628 \ -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-0-pro-260628/requests。运行被受理后，Router 会立即返回 201 和 request_id；结果就绪后，可以从本进程或其他进程收集。状态、取消与收集的细节见 队列投递。 ``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-0-pro-260628", { "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-0-pro-260628", { 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() 返回的结果相同。失败或已取消的请求会在此处 reject。 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-0-pro-260628/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-0-pro-260628/requests/$REQUEST_ID/status \ -H "X-API-Key: $COMFY_API_KEY" # 3. 收集。返回 200 和模型的原始输出；仍在运行期间则返回 202 和状态响应体。 curl https://api.comfy.org/v2/models/byteplus/seedream-5-0-pro-260628/requests/$REQUEST_ID \ -H "X-API-Key: $COMFY_API_KEY" ``

Schema

输入

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 支持该参数。 true: 图层分离模式。模型会将单张输入图像分解为一张基础图像加多个图层（最多 16 个），并返回每个生成图层的位置和内容信息，包括堆叠顺序（z\_index）、边界框（bounding\_box）、名称（name）和描述（description）。 false: 标准图像生成模式，不执行图层分离。 关于图层分离模式的说明：仅支持单张输入图像（传入多张图像会返回错误）；如果任何一个图层生成失败，整个请求都会失败，不支持部分成功；最多返回 17 张图像（1 张基础图像 + 16 个图层）。如果传入 sequential\_image\_generation、sequential\_image\_generation\_options、tools 和 stream，会返回错误。

model string

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

optimize\_prompt\_options object

提示词优化功能的配置。仅 seedream-5.0-pro/5.0-lite/4.5（仅支持 standard 模式）和 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 支持该参数。在图层分离场景中，output\_format 只控制基础图像的格式；每个图层始终以 png 输出。

可选值：png、jpeg

prompt string

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

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 不支持）。有效值： auto: 在自动模式下，模型根据用户的提示词自动判断是否返回多张图像以及其中包含多少张图像。 disabled: 禁用批处理生成功能。模型只会生成一张图像。

可选值：auto、disabled

sequential\_image\_generation\_options object

仅 seedream-5.0-lite、4.5 和 4.0 支持该参数（seedream-5.0-pro 和 5.0-flash 不支持）。 批处理图像生成功能的配置。该参数仅在 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-0-pro-260628" 和 "seedream-5-0-flash-260915" 在启用 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 不支持）。false = 所有输出图像一次性返回。true = 每张输出图像在生成后立即返回。

watermark boolean (default: true)

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

本文档由 Router 在 GET /v2/models/byteplus/seedream-5-0-pro-260628/openapi.json 提供的 schema 生成，与它在请求到达提供商之前用于校验调用的文档为同一份。

输出

created integer

指示请求创建时间的 Unix 时间戳（以秒为单位）

data object[]

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

data\[].b64\_json string

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

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 支持该字段。

data\[].size string

图像的宽度和高度（以像素为单位），格式为 \<width>x\<height>。仅 seedream-5.0-pro、5.0-lite、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 支持该字段。

usage.output\_tokens integer

模型生成图片所使用的 token 数量。

usage.total\_tokens integer

本次请求消耗的 token 总数。

示例

输入

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

输出

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

发布前须知

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

请求失败时，Router 会发送 X-Comfy-Error-Type 响应头说明原因。422 表示 Router 在调用提供商之前就拒绝了输入，413 表示请求体超出了 Router 可接受的大小。已生成的资源请及时下载，因为结果 URL 会过期。

上文任何字段描述中提到的尺寸限制，都是提供商对该字段自身的限定，引自提供商的规范。Router 会对整个请求体另行设置上限，base64 编码的媒体内容也计入其中：参见请求体大小。

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

[card] 请求头 身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
[card] 使用 Router API 模型发现、验证错误、重试与计费。
[card] 限制 Router 目前不支持的功能，以及替代方案。