Seedream
用 Seedream 生成和編輯圖片:參數、返回與注意事項。
| 項目 | 值 |
|---|---|
| Base URL | https://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.5 | seedream-5-5 | 1K / 1.5K / 2K | $0.02起/ 張 |
| Seedream 5.0 Pro | seedream-5-0-pro | 1K / 1.5K / 2K | $0.0225起/ 張 |
| Seedream 5.0 Lite | seedream-5-0-lite | 2K / 3K / 4K | $0.035/ 張 |
| Seedream 4.5 | seedream-4-5 | 2K / 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 | 選填 | 只能為 1 | 1 | 其他值(含 null)返回 400;要多張請用 sequential_image_generation |
response_format | 選填 | 只能為 url / b64_json | url | url 返回簽名直鏈;b64_json 在 data[].b64_json 返回 base64 |
output_format | 選填 | 依型號,見下表 | — | 輸出圖片格式 |
optimize_prompt_options | 選填 | 物件,mode 依型號取值 | — | 提示詞優化模式 |
image | 選填 | URL / Data URL,字串或字串陣列 | — | 參考圖,傳入即圖生圖 / 編輯 |
layer_decomposition | 選填 | 布林,僅 seedream-5-0-pro | false | true 把 1 張輸入圖拆成底圖 + 圖層,見圖層拆分 |
background | 選填 | opaque / transparent,僅 seedream-5-5 / seedream-5-0-pro | opaque | transparent 須恰好 1 張帶透明通道的輸入圖,見透明背景 |
watermark | 選填 | 布林 | false | true 加浮水印(官方預設 true) |
sequential_image_generation | 選填 | auto / disabled,僅 seedream-5-0-lite / seedream-4-5 | disabled | auto 返回一組圖,見組圖 |
sequential_image_generation_options | 選填 | 物件;max_images 為 1 至 15 的整數 | — | 組圖張數上限;參考圖數 + max_images ≤ 15 |
stream | 選填 | 布林,僅 seedream-5-0-lite / seedream-4-5 | false | true 返回 SSE,見串流 |
依型號的限制:
| 模型 ID | size 總像素 | 參考圖上限 | output_format | optimize_prompt_options.mode |
|---|---|---|---|---|
seedream-5-5 | 921,600–4,624,220 | 10 | png / jpeg | standard |
seedream-5-0-pro | 921,600–4,624,220 | 10 | png / jpeg | standard / fast |
seedream-5-0-lite | 3,686,400–16,777,216 | 14 | png / jpeg | standard |
seedream-4-5 | 3,686,400–16,777,216 | 14 | jpeg | standard |
寬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 傳字串 true | false | 須恰好 1 張 image |
請求裡帶 mask 欄位即返回 400,傳 null 也一樣。multipart 中上表以外的欄位會被忽略。
返回結果
同步返回標準 OpenAI Images JSON,圖片在 data[].url;傳 response_format: b64_json 時在 data[].b64_json。stream: true 時改為 SSE,見串流。
| 欄位 | 型別 | 說明 |
|---|---|---|
created | integer | Unix 秒 |
model | string | 請求的模型 ID |
data[].url | string | 圖片簽名直鏈,24 小時有效 |
data[].b64_json | string | base64 圖片資料,僅 response_format: b64_json 時返回 |
data[].error | object | 僅組圖:這一張產生失敗(code、message),不計費 |
data[].size | string | 實際輸出的 寬x高 |
usage | object | 可能返回,含 generated_images 等用量 |
usage.cost | number | 本次扣費的人民幣金額(與 usage.cost_usd 為同一筆扣費),最多 6 位小數。計費的同步成功回應都帶 |
usage.cost_usd | number | 本次實際從餘額扣除的美元金額,最多 8 位小數,與使用記錄裡這一條相同 |
usage.currency | string | usage.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_index | 0 是底圖;圖層從 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 描述。
- 複數
images、quality等欄位不生效,會被忽略。 - 暫不支援
tools(聯網搜尋),傳入返回 400。 seedream-5-0-lite是 Seedream 5.0 的輕量版,公開模型名為 Seedream 5.0 Lite,請勿當作 Pro 使用。- Data URL 必須是 base64 編碼,MIME 須與圖片一致。
- 官方規格:輸入單張最多 30 MB / 36MP。
常見報錯
參數不合規在生成前返回 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 background | background 請用 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 |
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size # 例如 "size": "auto"
model seedream-5-5 only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size # 例如 "size": "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
missing prompt
response_format only supports url or b64_json
only a single output is supported (n=1)
model seedream-4-5 only supports output_format jpeg
model seedream-5-0-lite only supports optimize_prompt_options.mode standard
model seedream-5-5 only supports optimize_prompt_options.mode standard # fast 僅 seedream-5-0-pro
optimize_prompt_options must be an object
image must be a URL/data URL string or an array of strings
every item in the image array must be a URL or data URL string
image must not be empty
at most 10 reference images are supported
reference image 1 is invalid: data URL must be base64-encoded
reference image 1 is invalid: unsupported image format image/svg+xml
reference image 1 is invalid: a single image must not exceed 30 MB
image edits require at least one image reference # /v1/images/edits 未帶圖
seedream does not accept a traditional mask; ... # /v1/images/edits 帶 "mask" 即拒,null 也一樣
model seedream-5-0-lite does not support layer_decomposition # 只有 seedream-5-0-pro 支援
layer_decomposition must be a boolean
layer_decomposition requires exactly one image # 沒傳圖,或傳了 2 張以上
layer_decomposition only accepts png or jpeg images # Data URL 是其他格式
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition
model seedream-5-0-lite does not support background # 僅 seedream-5-5 / seedream-5-0-pro 支援
model seedream-5-0-pro only supports background opaque or transparent
background transparent requires exactly one image with an alpha channel
background transparent outputs png; output_format jpeg is not allowed
background transparent requires an input image with an alpha channel, image/jpeg is not supported
model seedream-5-0-pro does not support sequential_image_generation # 組圖與串流:僅 seedream-5-0-lite / seedream-4-5
sequential_image_generation only supports auto or disabled
sequential_image_generation_options must be an object
sequential_image_generation_options.max_images must be an integer between 1 and 15
the number of reference images plus max_images must not exceed 15
response_format b64_json with sequential_image_generation auto requires stream=true
model seedream-5-0-pro does not support stream
watermark must be a boolean
model seedream-5-0-lite does not support 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 即計費的輸出張數。串流回應不帶扣費欄位,請看使用記錄。
單價見各型號的模型卡與登入後的模型廣場。