> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-chore-mintlify-theme-mint.mintlify.site/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?onboarding=router)中创建一个密钥，并将其导出为 `COMFY_API_KEY`。Python、TypeScript 和 Swift 代码片段使用 Comfy SDK（`pip install comfy-sdk`、`npm install @comfyorg/sdk`，以及 [`ComfySwiftSDK`](https://github.com/Comfy-Org/comfy-swift-sdk) Swift 包）；cURL 代码片段是通过原始 HTTP 发起的相同调用。

**模型 ID：** `byteplus/seedream-5-0-260128`

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

<Tabs>
  <Tab title="等待结果">
    <CodeGroup>
      ```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-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";

      // 从环境变量中读取 COMFY_API_KEY。
      // SDK 会自动创建幂等键，并在自动重试时复用它。
      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);
      ```

      ```swift Swift theme={null}
      import Foundation
      import ComfySwiftSDK

      // 从环境变量中读取 COMFY_API_KEY。
      // SDK 每次调用都会生成一个幂等键，并在自动重试时复用它。
      let client = ComfyCloudClient(apiKey: ProcessInfo.processInfo.environment["COMFY_API_KEY"]!)
      let result = try await client.models.run(
          "byteplus/seedream-5-0-260128",
          input: [
              "prompt": "A red fox trotting through a snowy pine forest, cinematic lighting",
              "response_format": "url",
              "watermark": false,
          ]
      )

      print(result.output)
      ```

      ```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}"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="排队并稍后收集">
    将相同的请求体发送到 `POST https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128/requests`。运行被受理后，Router 会立即返回 `201` 和 `request_id`；结果就绪后，可以从本进程或其他进程收集。状态、取消与收集的细节见 [队列投递](/zh/development/comfy-router/queue)。

    <CodeGroup>
      ```python Python theme={null}
      from comfy_sdk import Comfy

      # 从环境变量中读取 COMFY_API_KEY。
      # 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。
      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)  # 配合模型 ID，就是另一个进程所需的全部信息

          # 轮询直到请求完成，按服务器指定的 Retry-After 等待。
          for update in handle.iter_events():
              print(update.status, update.queue_position)

          # 提供商自身的负载，与 models.run() 返回的值相同。
          # 失败或已取消的请求会在此处抛出带类型的 Router 错误。
          result = handle.get()

      print(result)
      ```

      ```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-260128", {
        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);
      ```

      ```swift Swift theme={null}
      import Foundation
      import ComfySwiftSDK

      // 从环境变量中读取 COMFY_API_KEY。
      // 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。
      let client = ComfyCloudClient(apiKey: ProcessInfo.processInfo.environment["COMFY_API_KEY"]!)
      let handle = try await client.models.submit(
          "byteplus/seedream-5-0-260128",
          input: [
              "prompt": "A red fox trotting through a snowy pine forest, cinematic lighting",
              "response_format": "url",
              "watermark": false,
          ]
      )
      print("requestId:", handle.requestId)  // 配合模型 ID，就是另一个进程所需的全部信息

      // 轮询直到请求完成，按服务器指定的 Retry-After 等待。
      for try await update in handle.events() {
          print(update.state.rawValue, update.queuePosition.map(String.init) ?? "unknown")
      }

      // 提供商自身的负载，与 models.run() 返回的值相同。
      // 失败或已取消的请求会在此处抛出带类型的 Router 错误。
      let result = try await handle.result()

      print(result.output)
      ```

      ```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-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. 轮询直到状态为 COMPLETED，按每个响应指定的 Retry-After 秒数等待。
      REQUEST_ID="<request_id from the 201 body>"
      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. 收集。返回 200 时包含模型的原始输出，仍在运行时返回 202 及状态体。
      curl https://api.comfy.org/v2/models/byteplus/seedream-5-0-260128/requests/$REQUEST_ID \
        -H "X-API-Key: $COMFY_API_KEY"
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## 架构

### 输入

<ParamField body="guidance_scale" type="number">
  控制输出图像与输入提示词的贴合程度。范围 \[1, 10]。值越大，提示词的遵循程度越强。seedream-5.0-pro、5.0-lite、4.5 和 4.0 不支持。

  范围：`1` 到 `10`

  格式：`float`
</ParamField>

<ParamField body="image" type="string | string[]">
  Seedream-5.0-pro、5.0-lite、4.5 和 4.0 支持该参数。

  输入待编辑图像的 Base64 编码或可访问的 URL。Seedream-5.0-pro、5.0-lite、4.5 和 4.0 支持输入单张图像或多张图像（参见多图融合示例）。

  • 图片网址：请确保图片网址可访问。
  • Base64 编码：格式必须为 data:image/\<image format>;base64,\<Base64 encoding>。注意：\<image format> 必须为小写，例如 data:image/png;base64,\<base64\_image>。

  Comfy Router 将整个 JSON 请求限制为 100 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]
  • 宽度和高度（像素）：> 14
  • 大小：不超过 10 MB（seedream-5.0-pro 为 30 MB）
  • 总像素：对于 seedream-5.0-pro，不超过 6000x6000（36,000,000 像素）
  • 最多 14 张参考图像（seedream-5.0-pro 为 10 张）

  在图层分离场景中（启用 layer\_decomposition），image 为必填项，且仅支持单张输入图像（传入多张图像会返回错误）。输入图像必须为 png、jpeg、webp、bmp、tiff 或 gif（不支持 heic 和 heif），最大 30 MB，总像素范围在 \[512x512, 6000x6000]，宽高比例在 \[1/16, 16]。
</ParamField>

<ParamField body="layer_decomposition" type="boolean" default="false">
  控制是否启用图层分离。仅 seedream-5.0-pro 支持该参数。
  是：图层分离模式。模型将单张输入图像分解为一张基础图像加多个图层（最多 16 个），并返回每个生成图层的位置和内容信息，包括堆叠顺序（z\_index）、边界框（bounding\_box）、名称（name）和描述（description）。
  否：标准图像生成模式，不执行图层分离。
  图层分离模式注意事项：仅支持单张输入图像（传入多张图像会返回错误）；如果任一图层生成失败，整个请求都会失败，不支持部分成功；最多返回 17 张图像（1 张基础图像 + 16 个图层）。传入 sequential\_image\_generation、sequential\_image\_generation\_options、tools 和 stream 会返回错误。
</ParamField>

<ParamField body="model" type="string">
  模型标识符。支持的模型：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 调用方会省略该参数。
</ParamField>

<ParamField body="optimize_prompt_options" type="object">
  提示词优化功能的配置。仅 seedream-5.0-pro/5.0-lite/4.5（仅支持 standard 模式）和 seedream-4.0 支持该参数。
</ParamField>

<ParamField body="optimize_prompt_options.mode" type="string" default="&#x22;standard&#x22;">
  设置提示词优化功能的模式。standard = 质量更高，生成时间更长。fast = 速度更快，但质量较为一般。

  可能的值：`standard`、`fast`
</ParamField>

<ParamField body="output_format" type="string" default="&#x22;jpeg&#x22;">
  指定输出图像的格式。仅 seedream-5.0-pro 和 5.0-lite 支持该参数。在图层分离场景中，output\_format 仅控制基础图像的格式；每个图层始终以 png 格式输出。

  可能的值：`png`、`jpeg`
</ParamField>

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

<ParamField body="response_format" type="string" default="&#x22;url&#x22;">
  指定响应中返回的已生成图像的格式

  可能的值：`url`、`b64_json`
</ParamField>

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

  范围：`-1` 到 `2147483647`
</ParamField>

<ParamField body="sequential_image_generation" type="string">
  控制是否禁用批处理生成功能。该参数仅在 seedream-5.0-lite、4.5 和 4.0 上受支持（seedream-5.0-pro 不支持）。有效值：
  自动：在自动模式下，模型会根据用户提示词自动判断是否返回多张图像以及包含多少张图像。
  禁用：禁用批处理生成功能。模型只会生成一张图像。

  可能的值：`auto`、`disabled`
</ParamField>

<ParamField body="sequential_image_generation_options" type="object">
  仅 seedream-5.0-lite、4.5 和 4.0 支持该参数（seedream-5.0-pro 不支持）。
  批处理图像生成功能的配置。仅当 sequential\_image\_generation 设置为 auto 时，此参数才会生效。
</ParamField>

<ParamField body="sequential_image_generation_options.max_images" type="integer" default="15">
  指定本次请求中最多生成的图像数量。输入参考图像数量 + 已生成图像数量 ≤ 15。

  范围：`1` 到 `15`
</ParamField>

<ParamField body="size" type="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]
  启用 layer\_decomposition 的 "seedream-5-0-pro-260628"：仅支持分辨率级别的方法。可选值：1K、1.5K、2K、auto。默认：auto。
  基础图像按指定分辨率输出，并采用原始输入图像的宽高比；每个图层输出的尺寸接近指定分辨率，并保持其在原始图像中的宽高比。
  auto：根据输入图像的尺寸和宽高比进行输出。\[1280x720, \~2048x2048] 范围内的输入按原始输入尺寸输出；小于 1K 的输入按 1K 输出；大于 2K 的输入按 2K 输出。
</ParamField>

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

<ParamField body="watermark" type="boolean" default="true">
  指定是否为生成的图像添加水印。false = 无水印，true = 添加带 'AI generated' 标签的水印
</ParamField>

由 Router 在 `GET /v2/models/byteplus/seedream-5-0-260128/openapi.json` 提供的 schema 生成，该文档也是请求到达提供商之前用于校验调用的同一份文档。

### 输出

<ResponseField name="created" type="integer">
  Unix 时间戳（以秒为单位），表示请求创建的时间
</ResponseField>

<ResponseField name="data" type="object[]">
  包含已生成图像的相关信息。
  在图层分离场景中，数组的第一个元素是基础图像（z\_index=0），后续元素为各个图层，按 z\_index 递增排序。
</ResponseField>

<ResponseField name="data[].b64_json" type="string">
  Base64 编码的图像数据（当 response\_format 为 "b64\_json" 时）
</ResponseField>

<ResponseField name="data[].bounding_box" type="object">
  当前图层在基础图像中所占区域的边界框信息。仅图层会返回该字段；基础图像覆盖整个画布，不返回 bounding\_box。仅在 layer\_decomposition 为 true 时返回。
</ResponseField>

<ResponseField name="data[].bounding_box.absolute" type="integer[]">
  图层边界框的绝对像素坐标，以输出基础图像的坐标系为准，左上角为 (0, 0)。坐标格式：\[left, top, right, bottom]。
</ResponseField>

<ResponseField name="data[].bounding_box.normalized" type="integer[]">
  图层边界框的千分位量化（归一化）坐标，基于基础图像尺寸按比例映射到 \[0, 1000] 的离散整数范围，最大截断为 1000。坐标格式：\[left, top, right, bottom]。
</ResponseField>

<ResponseField name="data[].description" type="string">
  当前分离元素的详细描述，相比 name 提供更丰富的图层特征（如颜色、状态、材质）。仅图层会返回该字段；基础图像不返回。仅在 layer\_decomposition 为 true 时返回。
</ResponseField>

<ResponseField name="data[].name" type="string">
  当前分离元素的名称/标签，由模型根据分离主体的特征自动生成。仅图层会返回该字段；基础图像不返回。仅在 layer\_decomposition 为 true 时返回。
</ResponseField>

<ResponseField name="data[].output_format" type="string">
  输出图像的文件格式。仅 seedream-5.0-pro 支持该字段。
</ResponseField>

<ResponseField name="data[].size" type="string">
  图像的宽度和高度，以像素为单位，格式为 \<width>x\<height>。仅 seedream-5.0-pro、5.0-lite、4.5 和 4.0 支持该参数。
</ResponseField>

<ResponseField name="data[].url" type="string (uri)">
  用于下载图像的 URL（当 response\_format 为 "url" 时）

  格式：`uri`
</ResponseField>

<ResponseField name="data[].z_index" type="integer">
  图层的堆叠顺序，自下而上递增：0 是最底层的图层（基础图像）；数值越大位置越高。可用它按正确的堆叠顺序将图层重新合成为完整图像。仅在 layer\_decomposition 为 true 时返回。
</ResponseField>

<ResponseField name="error" type="object">
  错误信息（如有）
</ResponseField>

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

<ResponseField name="error.message" type="string">
  报错信息
</ResponseField>

<ResponseField name="model" type="string">
  用于该请求的模型 ID
</ResponseField>

<ResponseField name="usage" type="object" />

<ResponseField name="usage.generated_images" type="integer">
  模型生成的图像数量
</ResponseField>

<ResponseField name="usage.input_images" type="integer">
  输入模型的图像数量。仅 seedream-5.0-pro 支持该字段。
</ResponseField>

<ResponseField name="usage.output_tokens" type="integer">
  模型生成图片所使用的 token 数量。
</ResponseField>

<ResponseField name="usage.total_tokens" type="integer">
  本次请求消耗的 token 总数。
</ResponseField>

## 示例

### 输入

```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-0-260128",
  "usage": {
    "generated_images": 1
  }
}
```

## 发布前须知

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

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

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

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

<CardGroup cols={3}>
  <Card title="请求头" icon="list" href="/zh/development/comfy-router/headers">
    身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
  </Card>

  <Card title="使用 Router API" icon="code" href="/zh/development/comfy-router/api">
    模型发现、验证错误、重试与计费。
  </Card>

  <Card title="限制" icon="triangle-exclamation" href="/zh/development/comfy-router/limitations">
    Router 目前不支持的功能，以及替代方案。
  </Card>
</CardGroup>