跳到內容
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 “接下來”