Skip to content
RouteAPI RouteAPI

火山引擎 Seedream

当前在售的 Seedream 模型：seedream-5.0-pro 和 seedream-5.0-lite。它们由火山引擎（豆包）渠道提供，通过与 OpenAI 图像格式 相同的 OpenAI 兼容 images 端点调用；本页说明火山引擎适配器会做哪些改动。

Seedream 模型的 supported_endpoint_types 包含 image-generation——字段读法见模型。

端点

Section titled “端点”
POST /v1/images/generations
POST /v1/images/edits

/v1/images/generations 接收 JSON 请求体。图生图编辑使用 /v1/images/edits，把源图像作为字符串放在 image 字段；两者都会被转发到上游的图像生成端点（该渠道下火山引擎没有单独的表单编辑端点）。

请求参数

Section titled “请求参数”
字段类型必填说明
modelstring是seedream-5.0-pro 或 seedream-5.0-lite
promptstring是文本描述或编辑指令
sizestring否输出尺寸或档位。到达火山引擎前会做归一（见尺寸归一化）
imagestring否图生图的源图像，http(s) 链接或 data:image/...;base64,... 字符串。放在 JSON 请求体中传递
watermarkboolean否是否给输出加水印；显式传 false 会转发
sequential_image_generationstring否"auto" 开启多图生成，"disabled" 关闭
sequential_image_generation_optionsobject否连续生成的选项，{"max_images": <整数>} 指定数量
layer_decompositionboolean否把结果拆成分层图。开启后也会改变该请求的计价方式（见计费）
backgroundstring否背景处理，例如 "transparent" 或 "opaque"
toolsarray否上游工具，例如 [{"type": "web_search"}]
optimize_prompt_optionsobject否prompt 优化，例如 {"mode": "standard"} 或 {"mode": "fast"}

这些字段都属于网关的图像请求结构，会转发给火山引擎。未传的可选字段会从上游请求体中省略，而不是发送 null。其他网关不认识的 JSON 字段会被丢弃——如果确实需要网关未建模的字段，请在渠道上开启请求体透传。

尺寸归一化

Section titled “尺寸归一化”

size 的处理方式取决于模型：

模型size 处理
seedream-5.0-pro保留原生尺寸：1K、1.5K、1024x1024 这类像素值以及其他值都按传入值发送
seedream-5.0-lite逐像素尺寸会被改写为 2K / 3K / 4K 档位

对于会被改写的模型，长边决定档位：长边除以 1024 后四舍五入取整（正好 .5 时向上），再夹取到 2K–4K 区间。直接传档位（如 2K、3k）只做夹取，auto 这类无法识别的值原样透传，由火山引擎校验。seedream-5.0-lite 的示例：

请求的 size发给上游的值
1024x10242K
2048x20482K
1536x15362K
1440x25603K
3840x21604K
1K2K
5K4K
autoauto

生成图像

Section titled “生成图像”
Terminal window
curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "A misty mountain lake at sunrise, cinematic",
    "size": "2K"
  }'

连续生成

Section titled “连续生成”
Terminal window
curl https://api.routeapi.ai/v1/images/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite",
    "prompt": "A series of four postcards from the same coastal town, consistent style",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": { "max_images": 4 }
  }'

sequential_image_generation 为 "auto" 且没有给出 max_images 时，如果该模型配置了额外输出计价，预估计费会按 15 张图计算。

编辑图像

Section titled “编辑图像”

把源图像作为字符串放进 JSON 请求体。网关会把 image 的值原样转发给火山引擎——http(s) 链接或 data:image/...;base64,... 字符串都可以。上面的尺寸归一化同样作用于编辑请求。

Terminal window
curl https://api.routeapi.ai/v1/images/edits \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "Replace the background with a sunset beach, keep the subject unchanged",
    "image": "https://example.com/photo.png",
    "size": "2K"
  }'

layer_decomposition: true 要求上游把结果拆成独立图层；background: "transparent" 要求透明背景。两者都原样转发。

响应

Section titled “响应”

火山引擎的图像对象会原样返回给你。可以解析的字段如下：

{
  "data": [
    {
      "url": "https://example.com/generated.png",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "input_images": 1,
    "generated_images": 1,
    "output_tokens": 4096,
    "total_tokens": 4096
  }
}
  • 图像从 data[].url 读取。每一项可能带有实际交付的 size，它可能与你请求的档位不同。
  • 模型按张计费时，usage.input_images 和 usage.generated_images 用于结算；output_tokens 用于按 token 结算。

计费

Section titled “计费”

Seedream 模型在配置为按张计费时按张收费。如果模型详情页展示了尺寸档位，档位会在选择渠道之前，根据你发送的 size 对应的像素数确定。适用价格见模型定价与模型详情页。

Seedream 有两点特别注意：

  • 适配器会改写 seedream-5.0-lite 的 size，因此实际交付的图像可能落在与计费档位不同的档位上。为避免这种错配，按尺寸分档计价的模型如果被路由到火山引擎渠道，会以 400 拒绝；请求体透传模式不受影响，因为此时适配器不会改写请求体。
  • layer_decomposition: true 会切换到分层拆解的价格配置（仅在该模型配置了分层价格时）。免费额度之外的参考图以及连续生成的多张图也会计费，具体数字以模型详情页为准。

错误与限制

Section titled “错误与限制”
状态码含义常见原因
400请求无效缺少 model、n 超过 128、在 JSON 请求体中用 × 作为尺寸分隔符，或按尺寸分档计价的模型被路由到火山引擎
401认证失败API Key 缺失、无效、过期或额度耗尽
403余额或额度不足insufficient_user_quota 或 pre_consume_token_quota_failed
429触发限流降低并发
500转换或内部错误请求无法转换，或上游没有返回图像

不支持的 size、被拒绝的 prompt 等上游错误会带回上游的状态码与消息，并附加 RouteAPI 的请求 ID。

接下来

Section titled “接下来”