> ## 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.0 260128 > 通过 Comfy Router 调用 byteplus/seedream-5-0-260128：端点、请求形状以及 Router 返回的响应。 `byteplus/seedream-5-0-260128` 的 API 参考，由 Comfy Router 从 BytePlus 提供。 ## 快速开始在[你的 Comfy 工作区](https://platform.comfy.org/profile/api-keys)中创建一个密钥，并将其导出为 `COMFY_API_KEY`。Python 和 TypeScript 代码片段使用 Comfy SDK（`pip install comfy-sdk`、`npm install @comfyorg/sdk`）；cURL 代码片段是通过原始 HTTP 发起的相同调用。 **模型 ID：** `byteplus/seedream-5-0-260128` **端点：** `POST https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128` ```python Python theme={null} from comfy_sdk import Comfy # Reads COMFY_API_KEY from the environment. # The SDK automatically creates an idempotency key and reuses it for automatic retries. with Comfy() as client: result = client.models.run( "byteplus/seedream-5-0-260128", { "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"; // Reads COMFY_API_KEY from the environment. // The SDK automatically creates an idempotency key and reuses it for automatic retries. const { data } = await comfy.models.run("byteplus/seedream-5-0-260128", { 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-260128 \ -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}" ``` ```python Python theme={null} from comfy_sdk import Comfy # Reads COMFY_API_KEY from the environment. # Each submit() call mints its own Idempotency-Key and reuses it for automatic retries. with Comfy() as client: handle = client.models.submit( "byteplus/seedream-5-0-260128", { "prompt": "A red fox trotting through a snowy pine forest, cinematic lighting", "response_format": "url", "watermark": False, }, ) print("request_id:", handle.request_id) # with the model ID, all another process needs # Poll until the request completes, waiting the Retry-After the server names. for update in handle.iter_events(): print(update.status, update.queue_position) # The provider's own payload, the same value models.run() returns. # A request that failed or was cancelled raises the typed Router error here. result = handle.get() print(result) ``` ```typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // Reads COMFY_API_KEY from the environment. // Each submit() call mints its own Idempotency-Key and reuses it for automatic retries. const handle = await comfy.models.submit("byteplus/seedream-5-0-260128", { prompt: "A red fox trotting through a snowy pine forest, cinematic lighting", response_format: "url", watermark: false, }); console.log("requestId:", handle.requestId); // with the model ID, all another process needs // Poll until the request completes, waiting the Retry-After the server names. for await (const update of handle.events()) { console.log(update.status, update.queuePosition); } // The same result models.run() returns. A request that failed or was cancelled rejects here. const result = await handle.get(); console.log(result.data); ``` ```bash cURL theme={null} # 1. Submit. Router answers 201 with request_id, status_url, response_url and cancel_url. curl https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128/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. Poll until status is COMPLETED, waiting the Retry-After seconds each response names. REQUEST_ID="" curl -i https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128/requests/$REQUEST_ID/status \ -H "X-API-Key: $COMFY_API_KEY" # 3. Collect. 200 with the model's native output, 202 with the status body while it is still running. curl https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128/requests/$REQUEST_ID \ -H "X-API-Key: $COMFY_API_KEY" ``` ## 架构 ### 输入控制输出图像与输入提示词的贴合程度。范围为 \[1, 10]。值越高，对提示词的遵循越强。seedream-3-0-t2i-250415 默认为 2.5，seededit-3-0-i2i-250628 默认为 5.5。seedream-5.0-pro、5.0-lite、4.5 和 4.0 不支持此参数。范围：`1` 到 `10` 格式：`float` Seedream-5.0-pro、5.0-lite、4.5 和 4.0，以及 seededit-3.0-i2i 支持此参数。输入要编辑图像的 Base64 编码或可访问的 URL。Seedream-5.0-pro、5.0-lite、4.5 和 4.0 支持输入单张图像或多张图像（参见多图像混合示例），而 seededit-3.0-i2i 仅支持单图输入。 • 图像 URL：确保图像 URL 可访问。 • Base64 编码：格式必须为 data:image/\;base64,\。注意：\ 必须为小写，例如 data:image/png;base64,\。 Comfy Router 将整个 JSON 请求限制为 10 MiB，其中包括 base64 展开和所有参考图像。对于会超出此传输限制的输入，请使用 URL。输入图像必须满足以下要求： • 图像格式：jpeg、png（seedream-5.0-pro、5.0-lite、4.5 和 4.0 还支持 webp、bmp、tiff 和 gif；seedream-5.0-pro 还支持 heic 和 heif） • 宽高比（宽度/高度）：seedream-5.0-pro、5.0-lite、4.5 和 4.0 在 \[1/16, 16] 范围内；seededit-3.0-i2i 在 \[1/3, 3] 范围内 • 宽度和高度（像素）：> 14 • 大小：不超过 10 MB（seedream-5.0-pro 为 30 MB） • 总像素：seedream-5.0-pro 不超过 6000x6000（36,000,000 px） • 参考图像最多 14 张（seedream-5.0-pro 为 10 张）在图层分离场景中（启用 layer\_decomposition），image 为必填，且仅支持单张输入图像（传入多张图像会返回错误）。输入图像必须为 png、jpeg、webp、bmp、tiff 或 gif（不支持 heic 和 heif），最大 30 MB，总像素在 \[512x512, 6000x6000] 范围内，宽高比在 \[1/16, 16] 范围内。控制是否启用图层分离。仅 seedream-5.0-pro 支持此参数。是：图层分离模式。模型将单张输入图像分解为一张基础图像加多个图层（最多 16 个），并返回每个生成图层的位置和内容信息，包括堆叠顺序（z\_index）、边界框（bounding\_box）、名称（name）和描述（description）。否：标准图像生成模式；不执行图层分离。关于图层分离模式的说明：仅支持单张输入图像（传入多张图像会返回错误）；如果任一图层生成失败，整个请求都会失败，不支持部分成功；最多返回 17 张图像（1 张基础图像 + 16 个图层）。如果传入 sequential\_image\_generation、sequential\_image\_generation\_options、tools 和 stream，将返回错误。模型标识符。支持的模型：seedream-3-0-t2i-250415、seededit-3-0-i2i-250628、seedream-4-0-250828、seedream-4-5-251128、seedream-5-0-260128 和 seedream-5-0-pro-260628。直接对 POST /proxy/byteplus/api/v3/images/generations 发起 v1 调用时必须提供它；代理会拒绝任何其他值，若省略则返回 400。它不在此架构的 `required` 列表中，因为 Comfy Router 会从 /v2/models/byteplus/\{model} 的 `{model}` 路径段填充它，因此 Router 调用方可以省略。提示词优化功能的配置。仅 seedream-5.0-pro/5.0-lite/4.5（仅支持 standard 模式）和 seedream-4.0 支持此参数。设置提示词优化功能的模式。standard = 更高质量，生成时间更长。fast = 速度更快，但质量更一般。可能的值：`standard`、`fast` 指定输出图像的格式。仅 seedream-5.0-pro 和 5.0-lite 支持此参数。在图层分离场景中，output\_format 仅控制基础图像的格式；每个图层始终以 png 格式输出。可能的值：`png`、`jpeg` 用于图像生成或变换的文本描述。在图层分离场景中为可选（启用 layer\_decomposition 的 seedream-5.0-pro）：如果提供了提示词，模型会根据提示词意图识别并分离你指定的元素；如果未提供提示词，模型会自动检测图像中的所有主要元素并将其分离为独立图层。指定响应中返回的已生成图像的格式可能的值：`url`、`b64_json` 用于控制图像生成随机性的随机种子。范围：\[-1, 2147483647]。如果未指定，将自动生成种子。要复现相同的输出，请使用相同的种子值。范围：`-1` 到 `2147483647` 控制是否禁用批处理生成功能。此参数仅在 seedream-5.0-lite、4.5 和 4.0 上受支持（seedream-5.0-pro 不支持）。有效值： auto：在自动模式下，模型会根据用户的提示词自动判断是否返回多张图像以及包含多少张图像。 disabled：禁用批处理生成功能。模型将只生成一张图像。可能的值：`auto`、`disabled` 仅 seedream-5.0-lite、4.5 和 4.0 支持该参数（seedream-5.0-pro 不支持）。批处理图像生成功能的配置。该参数仅在 sequential\_image\_generation 设置为 auto 时生效。指定本次请求中生成图像的最大数量。输入参考图像的数量 + 生成图像的数量 ≤ 15。范围：`1` 到 `15` "seedream-3-0-t2i-250415"：指定生成图像的尺寸（宽 x 高，单位为像素）。必须介于 \[512x512, 2048x2048] 之间 "seededit-3-0-i2i-250628"：生成图像的宽度和高度像素值。目前仅支持 adaptive。 "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] 启用 layer\_decomposition 的 "seedream-5-0-pro-260628"：仅支持分辨率级别的方法。可选值：1K、1.5K、2K、auto。默认值：auto。基础图像按照指定分辨率输出，并保持原始输入图像的宽高比；每个图层按接近指定分辨率输出，并保持其在原始图像中的宽高比。 auto：根据输入图像的尺寸和宽高比进行输出。介于 \[1280x720, \~2048x2048] 范围内的输入按原始输入尺寸输出；小于 1K 的输入按 1K 输出；大于 2K 的输入按 2K 输出。 Comfy Router 将显式传入的 stream 标志设置为 false，因为它捕获的是完整的 JSON 结果。在 v1 代理上，该字段控制是否启用流式输出模式。仅 seedream-5.0-lite、4.5 和 4.0 支持该参数（seedream-5.0-pro 不支持）。false = 所有输出图像一次性返回。true = 每张输出图像在生成后立即返回。指定是否为生成图像添加水印。false = 不添加水印，true = 添加带有 "AI generated" 标签的水印根据 Router 在 `GET /v2/models/byteplus/seedream-5-0-260128/openapi.json` 提供的 schema 生成，该文档与请求到达提供商之前 Router 用于校验调用的文档相同。 ### 输出表示请求创建时间的 Unix 时间戳（以秒为单位）包含已生成图像的相关信息。在图层分离场景中，数组的第一个元素是基础图像（z\_index=0），后续元素是各个图层，按 z\_index 递增排序。 Base64 编码的图像数据（当 response\_format 为 "b64\_json" 时）当前图层在基础图像中所占区域的边界框信息。仅图层会返回该字段；基础图像覆盖整个画布，不返回 bounding\_box。仅当 layer\_decomposition 为 true 时返回。图层边界框的绝对像素坐标，以输出基础图像的坐标系为准，左上角为 (0, 0)。坐标格式：\[left, top, right, bottom]。图层边界框的千分比量化（归一化）坐标，基于基础图像尺寸按比例映射到 \[0, 1000] 的离散整数范围，最大截断为 1000。坐标格式：\[left, top, right, bottom]。当前分离元素的详细描述，相比 name 提供了更丰富的图层特征（如颜色、状态、材质）。仅图层会返回该字段；基础图像不返回。仅当 layer\_decomposition 为 true 时返回。当前分离元素的名称/标签，由模型根据分离主体的特征自动生成。仅图层会返回该字段；基础图像不返回。仅当 layer\_decomposition 为 true 时返回。输出图像的文件格式。仅 seedream-5.0-pro 支持该字段。图像的宽度和高度，以像素为单位，格式为 \x\。仅 seedream-5.0-pro、5.0-lite、4.5 和 4.0 支持该参数。图像下载 URL（当 response\_format 为 "url" 时）格式：`uri` 图层的堆叠顺序，自下而上递增：0 为最底层（基础图像）；数值越大层级越高。可用它按正确的堆叠顺序将各图层重新合成为完整图像。仅当 layer\_decomposition 为 true 时返回。错误信息（如有）错误码报错信息请求所使用的模型 ID 模型已生成的图像数量输入到模型的图像数量。仅 seedream-5.0-pro 支持该字段。模型生成图片所使用的 token 数量。本次请求消耗的 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-3-0-t2i-250415/generated.png" } ], "model": "seedream-5-0-260128", "usage": { "generated_images": 1 } } ``` ## 发布前须知 SDK 会生成 `Idempotency-Key` 并在自动重试中复用它。手动重试时，请复用原始 key。Router 最长可保持连接 10 分钟。请求失败时，Router 会发送 `X-Comfy-Error-Type` 响应头说明原因。`422` 表示 Router 在调用提供商之前就拒绝了输入。生成的资源请及时下载，因为[结果链接会过期](/zh/development/comfy-router/reference#结果资产)。身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。模型发现、校验错误、重试与计费。 Router 目前不支持的功能，以及替代方案。