byteplus/seedream-4-0-250828 的 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-4-0-250828
端点: POST https://api.comfy.org/v2/models/byteplus/seedream-4-0-250828
- 等待结果
- 排队并稍后收集
同一个请求体,发送到
POST https://api.comfy.org/v2/models/byteplus/seedream-4-0-250828/requests。运行被受理后,Router 会立即返回 201 和 request_id;结果就绪后,可以从本进程或其他进程收集。状态、取消与收集的完整说明见 队列投递。Schema
输入
控制生成图像是否具有透明背景(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控制输出图像与输入提示词的贴合程度。范围 [1, 10]。值越大,对提示词的遵循越强。seedream-5.0-pro、5.0-lite、4.5 和 4.0 不支持该参数。范围:
1 到 10格式:floatSeedream-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]
• 宽度和高度(px):> 14
• 大小:不超过 10 MB(seedream-5.0-pro 为 30 MB)
• 总像素:对于 seedream-5.0-pro,不超过 6000x6000(36,000,000 px)
• 最多 14 张参考图像(seedream-5.0-pro、5.0-flash 和 5.5 为 10 张)在图层分离场景中(启用 layer_decomposition),image 为必填项,并且仅支持单张输入图像(传入多张图像会返回错误)。输入图像必须为 png、jpeg、webp、bmp、tiff 或 gif(不支持 heic 和 heif),最大 30 MB,总像素在 [512x512, 6000x6000] 范围内,宽高比在 [1/16, 16] 范围内。
控制是否启用图层分离。仅 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,会返回错误。
此请求返回的图像总数上限,包括基础图像和所有图层。范围:[2, 100]。当提示词未说明如何拆分图像时,模型会根据 max_images 和输入图像的复杂程度规划图层;通常值越大,图层划分越精细。范围:
2 到 100模型标识符。支持的模型: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。直接向 POST /proxy/byteplus/api/v3/images/generations 发起 v1 调用时必须提供该参数;代理会拒绝任何其他值,若省略该参数也会返回 400 错误。它不在此 schema 的
required 列表中,因为 Comfy Router 会从 /v2/models/byteplus/{model} 的 {model} 路径段填充它,因此 Router 调用方会省略该参数。提示词优化功能的配置。仅 seedream-5.0-pro/5.0-lite/4.5/5.5(仅支持 standard 模式;seedream-5.5 对 fast 返回错误)和 seedream-4.0 支持该参数。
设置提示词优化功能的模式。
standard = 质量更高,生成时间更长。
fast = 速度更快,但质量较为一般。可能的值:
standard、fast指定输出图像的格式。仅 seedream-5.0-pro、5.0-flash、5.0-lite 和 5.5 支持该参数。seedream-5.5 默认为 png。在图层分离场景中,output_format 仅控制基础图像的格式;每个图层始终以 png 输出。可能的值:
png、jpeg用于图像生成或转换的文本描述。
在图层分离场景中为可选项(seedream-5.0-pro、5.0-flash 或启用了 layer_decomposition 的 5.5):如果提供了提示词,模型会按提示词意图识别并分离你指定的元素;如果未提供提示词,模型会自动检测图像中的所有主要元素,并将其分离为独立图层。
用于控制图像生成随机性的随机种子。范围:[-1, 2147483647]。如果未指定,将自动生成种子。若要复现相同的输出,请使用相同的种子值。范围:
-1 到 2147483647控制是否禁用批处理生成功能。此参数仅在 seedream-5.0-lite、4.5 和 4.0 上受支持(seedream-5.0-pro、5.0-flash 或 5.5 不支持)。有效值:
auto:在自动模式下,模型根据用户的提示词自动决定是否返回多张图像以及包含多少张图像。
disabled:禁用批处理生成功能。模型将仅生成一张图像。可能的值:
auto、disabled仅 seedream-5.0-lite、4.5 和 4.0 支持此参数(seedream-5.0-pro、5.0-flash 或 5.5 不支持)。
批处理图像生成功能的配置。此参数仅在 sequential_image_generation 设置为 auto 时生效。
“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 输出。
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 = 每张输出图像生成后立即返回。
GET /v2/models/byteplus/seedream-4-0-250828/openapi.json 提供的 schema 生成,该文档与请求到达提供商之前校验调用所用的文档相同。
输出
图像实际具有的背景类型:transparent 或 opaque。在图层分离场景中,基础图像始终为 opaque,每个图层均为 transparent。仅 seedream-5.5 返回该字段。
图层边界框的千分位量化(归一化)坐标,基于基础图像尺寸按比例映射到 [0, 1000] 的离散整数区间,最大截断为 1000。坐标格式:[left, top, right, bottom]。
对当前分离元素的详细描述,相比 name 提供更丰富的图层特征(如颜色、状态、材质)。仅图层返回该字段,基础图像不返回。仅当 layer_decomposition 为 true 时返回。
图层的堆叠顺序,自下而上递增:0 为最底层(基础图像);数值越大位置越高。可使用它按正确的堆叠顺序将各图层重新合成为完整图像。仅当 layer_decomposition 为 true 时返回。
上游 ModelArk 错误码。SensitiveContentDetected、InputTextSensitiveContentDetected、InputImageSensitiveContentDetected、InputVideoSensitiveContentDetected、InputAudioSensitiveContentDetected、OutputTextSensitiveContentDetected、OutputImageSensitiveContentDetected、OutputVideoSensitiveContentDetected 和 OutputAudioSensitiveContentDetected 表示因内容策略而被拒绝。同一族错误码可能带有以点分隔的原因,例如 InputImageSensitiveContentDetected.PrivacyInformation、OutputVideoSensitiveContentDetected.PolicyViolation 或 OutputImageSensitiveContentDetected.DeepFake。这是一个开放字符串,而非枚举:其他错误码用于描述验证失败和提供商故障。Router 会在 HTTP 400 错误响应和 HTTP 200 失败任务响应中识别内容策略族错误,但不会覆盖传输层故障。
示例
输入
输出
发布前须知
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。
请求头
身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
使用 Router API
模型发现、验证错误、重试与计费。
限制
Router 目前不支持的功能,以及替代方案。