跳到正文

Seedream

用 Seedream 生成和編輯圖片:參數、返回與注意事項。

項目值
Base URLhttps://api.hop-base.com/v1
生成(含參考圖編輯)POST /v1/images/generations
編輯(multipart 相容入口)POST /v1/images/edits
密鑰分組「Seedream 生圖分組」

Seedream 同步返回結果(Lite 與 4.5 也可串流返回)。n 固定為 1,除組圖與圖層拆分外每次出 1 張;圖片連結 24 小時有效。

可用型號

型號模型 ID尺寸簡寫官方價
Seedream 5.5seedream-5-51K / 1.5K / 2K$0.02起/ 張
Seedream 5.0 Proseedream-5-0-pro1K / 1.5K / 2K$0.0225起/ 張
Seedream 5.0 Liteseedream-5-0-lite2K / 3K / 4K$0.035/ 張
Seedream 4.5seedream-4-52K / 4K$0.04/ 張

選型建議:要 1K 小圖只能用 5.5 或 5.0 Pro,兩者都是 1.5K 與 1K 同價、效果更好,建議優先 1.5K;Lite 與 4.5 最小輸出 2K。

請求參數

生成

POST /v1/images/generations,JSON 請求體。加上 image 即為單圖編輯、多圖融合或局部編輯。

參數必填型別與限制預設說明
model必填字串,見上表—以目前密鑰 GET /v1/models 的返回為準
prompt必填字串,去除首尾空白後非空—內容、構圖、風格或編輯指令;開啟 layer_decomposition 時可省略
size選填型號尺寸簡寫,或 寬x高—僅 layer_decomposition 時可用 auto,像素範圍見下表
n選填只能為 11其他值(含 null)返回 400;要多張請用 sequential_image_generation
response_format選填只能為 url / b64_jsonurlurl 返回簽名直鏈;b64_json 在 data[].b64_json 返回 base64
output_format選填依型號,見下表—輸出圖片格式
optimize_prompt_options選填物件,mode 依型號取值—提示詞優化模式
image選填URL / Data URL,字串或字串陣列—參考圖,傳入即圖生圖 / 編輯
layer_decomposition選填布林,僅 seedream-5-0-profalsetrue 把 1 張輸入圖拆成底圖 + 圖層,見圖層拆分
background選填opaque / transparent,僅 seedream-5-5 / seedream-5-0-proopaquetransparent 須恰好 1 張帶透明通道的輸入圖,見透明背景
watermark選填布林falsetrue 加浮水印(官方預設 true)
sequential_image_generation選填auto / disabled,僅 seedream-5-0-lite / seedream-4-5disabledauto 返回一組圖,見組圖
sequential_image_generation_options選填物件;max_images 為 1 至 15 的整數—組圖張數上限;參考圖數 + max_images ≤ 15
stream選填布林,僅 seedream-5-0-lite / seedream-4-5falsetrue 返回 SSE,見串流

依型號的限制:

模型 IDsize 總像素參考圖上限output_formatoptimize_prompt_options.mode
seedream-5-5921,600–4,624,22010png / jpegstandard
seedream-5-0-pro921,600–4,624,22010png / jpegstandard / fast
seedream-5-0-lite3,686,400–16,777,21614png / jpegstandard
seedream-4-53,686,400–16,777,21614jpegstandard

寬x高 的寬高比須在 1:16–16:1 之間。size 不合規時在生成前返回 400,不計費。

image 的每一項是 http(s) URL 或 base64 編碼的 Data URL,Data URL 單張 ≤ 30 MB。支援 JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF;URL 在提交時不下載、不檢查大小,須是服務端能取得的公開位址。

局部編輯不用遮罩:把標註直接畫在參考圖上,並在 prompt 中描述座標、bbox、箭頭或塗畫區域。

編輯

POST /v1/images/edits 是給既有 OpenAI Images 編輯程式碼用的相容入口,推薦 multipart/form-data,也接受與生成相同的 JSON。至少要帶 1 張參考圖。

參數必填型別與限制預設說明
image / image[]必填檔案或 URL 字串,可重複—上傳檔案單張 ≤ 30 MB
model、prompt必填同「生成」——
size、n、response_format、output_format選填同「生成」——
background、watermark、stream、sequential_image_generation選填同「生成」—multipart 裡布林值寫字串 true / false
sequential_image_generation_options[max_images]選填同「生成」的 max_images—也可寫 max_images
optimize_prompt_options[mode]選填同「生成」的 mode—也可寫 optimize_prompt_mode
layer_decomposition選填同「生成」;multipart 傳字串 truefalse須恰好 1 張 image

請求裡帶 mask 欄位即返回 400,傳 null 也一樣。multipart 中上表以外的欄位會被忽略。

返回結果

同步返回標準 OpenAI Images JSON,圖片在 data[].url;傳 response_format: b64_json 時在 data[].b64_json。stream: true 時改為 SSE,見串流。

欄位型別說明
createdintegerUnix 秒
modelstring請求的模型 ID
data[].urlstring圖片簽名直鏈,24 小時有效
data[].b64_jsonstringbase64 圖片資料,僅 response_format: b64_json 時返回
data[].errorobject僅組圖:這一張產生失敗(code、message),不計費
data[].sizestring實際輸出的 寬x高
usageobject可能返回,含 generated_images 等用量
usage.costnumber本次扣費的人民幣金額(與 usage.cost_usd 為同一筆扣費),最多 6 位小數。計費的同步成功回應都帶
usage.cost_usdnumber本次實際從餘額扣除的美元金額,最多 8 位小數,與使用記錄裡這一條相同
usage.currencystringusage.cost 的幣別,恆為 CNY
{
  "model": "seedream-5-0-pro",
  "created": 1760000000,
  "data": [
    {
      "url": "https://…/result.jpeg?X-Signature=…",
      "size": "2048x2048"
    }
  ],
  "usage": {
    "generated_images": 1,
    "output_tokens": 16384,
    "total_tokens": 16384,
    "cost": 1.53,
    "cost_usd": 0.225,
    "currency": "CNY"
  }
}

同步成功回應還帶本次實際扣費:回應內容的 usage.cost、usage.cost_usd 與 usage.currency,以及值相同的回應標頭 X-HopBase-Cost、X-HopBase-Cost-USD 與 X-HopBase-Currency。產生耗時較長(約 40 秒以上)、伺服器已先送出 200 回應標頭維持連線時,回應標頭裡沒有扣費,請以回應內容的 usage.cost_usd(美元,與使用記錄一致)或 usage.cost(人民幣)對賬。未扣費的失敗不帶這些欄位,串流回應也不帶(請看使用記錄)。詳見扣費說明。

結果要立即下載:

返回的 URL 是 24 小時有效的簽名直鏈,過期後無法重新取得、只能重新生成(會再次計費),請收到後立即下載。

示例

文生圖

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "prompt": "霓虹夜色下的未來城市街景,電影感構圖",
    "size": "2048x2048",
    "response_format": "url"
  }'

參考圖編輯

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "prompt": "把第一張圖中的杯子移到桌面右側,保持其餘內容不變",
    "image": ["https://example.com/source.png"],
    "size": "2K",
    "output_format": "png",
    "response_format": "url"
  }'

組圖

seedream-5-0-lite 與 seedream-4-5 可以一次返回一組相關的圖(n 仍為 1)。傳 "sequential_image_generation": "auto":模型依 prompt 決定出幾張,不超過 sequential_image_generation_options.max_images(1 至 15 的整數;參考圖數 + max_images 不超過 15)。請在 prompt 裡描述整組內容,例如「同一角色四季的四張插畫」。/v1/images/edits 的 multipart 寫 sequential_image_generation_options[max_images](或 max_images)。

  • 只按成功的張數計費。失敗的那張(多為內容審核)以 data[].error(含 code、message)返回、不計費;全部失敗時請求返回 400 並帶原因。
  • 非串流組圖要等整組產生完才返回,伺服器最多等約 280 秒;張數多時請加 stream: true 逐張接收。非串流組圖不能用 response_format: b64_json。
curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "model": "seedream-5-0-lite",
    "prompt": "同一隻柴犬春夏秋冬的四張插畫",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": { "max_images": 4 },
    "size": "2K"
  }'

串流

seedream-5-0-lite 與 seedream-4-5 接受 "stream": true,單圖與組圖都可用,回應為 SSE(text/event-stream)。seedream-5-5 與 seedream-5-0-pro 返回 400。

事件data
image_generation.partial_succeeded一張圖完成:image_index、url(或 b64_json)、size
image_generation.partial_failed一張圖失敗:image_index、error.code、error.message;不計費
image_generation.completed全部結束:usage.generated_images、usage.output_tokens、usage.total_tokens

每個事件的 data 都帶 type、model、created,串流以 data: [DONE] 結束。按成功張數計費。串流回應不帶 usage.cost 與 X-HopBase-Cost 等回應標頭,扣費請看控制台使用記錄。

curl -N https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-lite",
    "prompt": "同一隻柴犬春夏秋冬的四張插畫",
    "sequential_image_generation": "auto",
    "sequential_image_generation_options": { "max_images": 4 },
    "stream": true
  }'
event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","model":"seedream-5-0-lite","created":1792723998,"image_index":0,"url":"https://…","size":"2048x2048"}

event: image_generation.completed
data: {"type":"image_generation.completed","model":"seedream-5-0-lite","created":1792723998,"usage":{"generated_images":1,"output_tokens":16384,"total_tokens":16384}}

data: [DONE]

透明背景

seedream-5-5 與 seedream-5-0-pro 接受 background:opaque / transparent,預設 opaque。transparent 只用於圖生圖:須恰好 1 張帶透明通道的輸入圖,例如 PNG(JPEG、BMP 的 Data URL 返回 400)。輸出為帶透明通道的 PNG,所以 output_format: jpeg 返回 400。其他型號傳 background 返回 400。

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -F "model=seedream-5-0-pro" \
  -F "prompt=保留商品主體,背景改為透明" \
  -F "image=@product.png" \
  -F "background=transparent" \
  -F "output_format=png"

圖層拆分

seedream-5-0-pro 可以把 1 張圖拆成底圖 + 至多 16 個透明圖層(主體、文字、背景、裝飾),方便逐層修改或挪動後再合成。在 POST /v1/images/generations 傳 JSON 布林 "layer_decomposition": true,或在 POST /v1/images/edits 傳欄位 layer_decomposition=true(multipart 或 JSON 皆可)。

開啟後以下規則改變:

參數layer_decomposition: true 時
model僅 seedream-5-0-pro,其他型號返回 400
image恰好 1 張;Data URL 須為 PNG 或 JPEG
prompt選填。不傳時模型自動辨識主體、文字、背景與裝飾;也可描述要拆出的內容,或用 <bbox>x1 y1 x2 y2</bbox>(0–999 正規化座標)指定區域
size只認 1K / 1.5K / 2K / auto,預設 auto;不接受 寬x高
output_format只作用於底圖;圖層恆為帶透明通道的 PNG

auto 時,輸入圖介於約 1280x720 與 2048x2048 之間則保持原尺寸,更小輸出 1K、更大輸出 2K。輸入圖官方限制:總像素 512x512 至 6000x6000,寬高比 1:16 至 16:1,不超過 30 MB。

用戶端逾時要設長:

圖層拆分是同步呼叫且較慢:1K 約需 1.5 分鐘。請把用戶端逾時設為至少 5 分鐘;第一個請求還在進行時不要重送,它仍可能完成並計費。

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "model": "seedream-5-0-pro",
    "image": "https://example.com/poster.png",
    "layer_decomposition": true,
    "size": "1K"
  }'

data[] 先是底圖,後面是各圖層:

{
  "model": "seedream-5-0-pro",
  "created": 1792722728,
  "data": [
    {
      "url": "https://…/base.jpeg?X-Signature=…",
      "size": "880x1088",
      "output_format": "jpeg",
      "z_index": 0
    },
    {
      "url": "https://…/layer-1.png?X-Signature=…",
      "size": "959x354",
      "output_format": "png",
      "z_index": 1,
      "bounding_box": {
        "absolute": [156, 751, 784, 983],
        "normalized": [177, 690, 890, 903]
      },
      "name": "Wooden stump stage",
      "description": "A wooden stump stage at the bottom of the scene"
    }
  ],
  "usage": {
    "generated_images": 2
  }
}
欄位說明
data[].z_index0 是底圖;圖層從 1 起遞增,數字越大越靠上
data[].url簽名直鏈,24 小時有效
data[].size這張圖的實際像素尺寸;圖層圖片尺寸通常與它在底圖上的框不同
data[].output_format底圖依請求的 output_format;圖層為 png
data[].bounding_box.absolute僅圖層:在底圖上的 [left, top, right, bottom] 像素座標
data[].bounding_box.normalized僅圖層:同一框的 0–999 正規化座標
data[].name、data[].description僅圖層:圖層名稱與內容描述
usage.generated_images底圖 + 圖層的張數,即計費張數

合成時以底圖為畫布,依 z_index 由小到大疊放:把每個圖層縮放到框的尺寸 (right - left) x (bottom - top),依透明通道貼到 (left, top)。以 Pillow 為例:

import io
import urllib.request
from PIL import Image

def fetch(url):
    return Image.open(io.BytesIO(urllib.request.urlopen(url).read())).convert("RGBA")

items = sorted(resp["data"], key=lambda d: d["z_index"])  # resp 為解析後的回應 JSON
canvas = fetch(items[0]["url"])
for item in items[1:]:
    left, top, right, bottom = item["bounding_box"]["absolute"]
    layer = fetch(item["url"]).resize((right - left, bottom - top))
    canvas.alpha_composite(layer, (left, top))
canvas.save("recomposed.png")

注意事項

  • n 只能為 1:每次出 1 張,組圖(sequential_image_generation: auto,Lite 與 4.5)與圖層拆分(5.0 Pro)除外。
  • 只支援同步:Prefer: respond-async 會被忽略,照常同步返回。
  • 預設返回 url;要 base64 請傳 response_format: b64_json(非串流組圖須同時 stream: true)。
  • size 不接受 auto(圖層拆分除外),Lite 與 4.5 的最小輸出是 2K。
  • seedream-4-5 只輸出 JPEG。
  • seedream-5-5 的 optimize_prompt_options.mode 只接受 standard(傳 fast 返回 400),不支援圖層拆分、組圖與串流。
  • 不支援傳統 mask,局部編輯請用帶標註的參考圖加 prompt 描述。

常見報錯

參數不合規在生成前返回 400,不計費。內容安全攔截也返回 400、不計費,原因在 error.message 中。

報錯改法
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size改用該型號的尺寸簡寫或合法 寬x高
model seedream-5-5 only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size改用 1K、1.5K、2K 或合法 寬x高;不接受 4K
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216把寬高調到總像素區間內
size aspect ratio must be between 1:16 and 16:1調整寬高比
only a single output is supported (n=1)去掉 n;要多張請用 sequential_image_generation
response_format only supports url or b64_json改為 url 或 b64_json
model seedream-4-5 only supports output_format jpeg改傳 jpeg 或不傳
model seedream-5-5 only supports optimize_prompt_options.mode standard改傳 standard 或不傳;fast 請用 seedream-5-0-pro
at most 10 reference images are supported減少參考圖張數
seedream does not accept a traditional mask; ...去掉 mask,改用帶標註的參考圖
model seedream-5-0-lite does not support layer_decomposition圖層拆分請用 seedream-5-0-pro
layer_decomposition requires exactly one image只傳 1 張 image
layer_decomposition only accepts png or jpeg images把輸入圖轉成 PNG 或 JPEG
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition改用檔位,或不傳 size
layer_decomposition must be a boolean傳 true 或 false
model seedream-5-0-lite does not support backgroundbackground 請用 seedream-5-5 或 seedream-5-0-pro
background transparent requires exactly one image with an alpha channel只傳 1 張帶透明通道的圖,例如 PNG
background transparent outputs png; output_format jpeg is not allowed去掉 output_format 或改為 png
model seedream-5-0-pro does not support sequential_image_generation組圖請用 seedream-5-0-lite 或 seedream-4-5
the number of reference images plus max_images must not exceed 15調小 max_images 或少傳參考圖
response_format b64_json with sequential_image_generation auto requires stream=true加 stream: true,或改用 url
model seedream-5-0-pro does not support stream串流請用 seedream-5-0-lite 或 seedream-4-5
model seedream-5-0-lite does not support tools去掉 tools

計費

按成功產生的張數計費(組圖裡失敗的那幾張不計費),5.5 與 5.0 Pro 每張參考圖另外計費;生成失敗與安全攔截不計費。5.5 與 5.0 Pro 按輸出像素分檔計價,1K 與 1.5K 同價。每次請求的實際扣費見回應裡的 usage.cost_usd(美元)與 usage.cost(人民幣)。圖層拆分時,每張輸出圖(底圖和每個圖層)各依自身像素檔以圖層拆分單價計費,為 5.0 Pro 一般單張價的一半;輸入圖照常按參考圖計費。usage.generated_images 即計費的輸出張數。串流回應不帶扣費欄位,請看使用記錄。

單價見各型號的模型卡與登入後的模型廣場。

下一步