Seedream 5.5 API 教學：Python 程式碼、價格與實際輸出

要呼叫 Seedream 5.5 API，請向 https://api.seedrouter.ai/v1/images/generations 傳送 POST 請求，帶上 "model": "seedream-5-5" 與提示詞，保留回傳的任務 id，再輪詢 GET /v1/tasks/{id}，直到狀態變成 completed。 完成的任務裡就有影像 URL。同一個請求也能使用最多 10 張參考圖編輯、生成透明背景的 PNG，以及將一張影像分解為透明圖層。

ByteDance 於 2026 年 11 月 9 日發布 Seedream 5.5，主要有三項變化：更穩定的多輪編輯、原生透明輸出，以及更真實的影像與更清晰的小字。^[1] 隔天，我們在 SeedRouter 上執行了三次。本教學就以這三次測試為例，列出傳送的程式碼、回傳的結果、耗時與費用。所有欄位請見 Seedream 5.5 API 參考文件，Playground 位於模型頁面。

第一次呼叫 Seedream 5.5 API 前需要準備什麼？

兩樣東西：一把 API 金鑰與模型 ID。沒有需要下載的模型檔案。ByteDance 尚未發布 Seedream 5.5 權重，因此模型以託管 API 執行，你的程式碼只需傳送 JSON。

在 API 金鑰 頁面建立金鑰，並保存在伺服器的環境變數裡，絕不要放進瀏覽器端程式碼：

export SEEDROUTER_API_KEY="your-key"
pip install requests

模型 ID 是 seedream-5-5。文生圖、編輯與圖層分解都使用同一個 ID，由請求欄位決定執行哪一種操作。新帳戶有少量免費餘額，足夠先測試幾張 1K 影像，再決定是否儲值。

如何用 Python 生成影像？

提交後會立即回傳任務，而不是影像。這個指令碼會提交提示詞，每 10 秒輪詢一次，15 分鐘後停止等待，並儲存每張回傳的影像。

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    r = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    return r.json()["id"]


def wait(task_id, limit=900):
    deadline = time.time() + limit
    while time.time() < deadline:
        r = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()
        if task["status"] in ("completed", "failed"):
            return task
        time.sleep(10)
    raise TimeoutError(f"{task_id} is still running; poll it again later")


task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A ceramic teapot shaped like a sleeping fox on a linen tablecloth, "
              "soft morning window light, shallow depth of field. No text.",
    "size": "1K",
})
task = wait(task_id)
if task["status"] == "failed":
    raise RuntimeError(task["error"]["message"])

for i, image in enumerate(task["output"]["data"]):
    data = requests.get(image["url"], timeout=60).content
    with open(f"seedream-{i}.{image['output_format']}", "wb") as f:
        f.write(data)
    print(image["size"], image["url"])

這就是我們的第一次測試。耗時 47 秒，回傳一張 1248 × 832 的 PNG。

這個迴圈裡有兩個習慣對正式環境很重要。輪詢逾時後，保留任務 ID 並繼續查詢，影像可能還在生成中。不要為了「重試」而再次傳送請求，因為這會建立第二個任務，並再次收費。

哪些請求欄位需要留意？

多數請求只需要 model、prompt 與 size。最常設定的欄位與預設值如下：

最大輸出為 2K。我們在 2K 下進行的 16:9 編輯回傳了 2560 × 1440，精確像素尺寸的總像素最高可達 4,624,220。沒有寬高比欄位：若要固定畫面形狀，請傳入精確像素尺寸。沒有 3K 或 4K 級距，若需要更大的檔案，就必須事後放大。API 參考文件列出所有欄位。文件未列出的欄位會被捨棄，不會導致請求被拒絕，因此誤帶其他影像 API 的 seed、style 或 n 不會讓請求失敗，也不會產生任何作用。一次請求生成一張影像。

如何用參考圖編輯影像？

將原圖放入 image，在提示詞中說明要修改與保留的內容。我們的第二次測試，將晴天裡一名油漆工站在燈塔環廊上的照片改成冬夜：

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "Turn this scene into a snowy winter night with warm light from "
              "the lighthouse windows, keep the composition",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/lighthouse-source.webp",
    "size": "2560x1440",
})

耗時 40 秒，回傳一張 2560 × 1440 的 PNG。油漆工、他的姿勢、刷子、盤繞的繩索、兩個油漆桶與欄杆都留在原位。畫面新增了飄雪、平台與肩膀上的積雪、暗色天空，以及塔身紅色條帶上方亮起的窗戶。

使用多張參考圖時，請依清單順序指稱（例如「圖 2 中的夾克」）。每張參考圖皆會計費，第一張也收費，因此僅傳送編輯所需的影像。

ByteDance 對這個版本的主要主張是，未編輯區域能在多次編輯中保持像素級一致，並已經過連續 100 輪測試。^[1] 透過 API 進行多輪編輯就是一個迴圈：取出完成任務中的 URL，作為下一次請求的 image 傳入。我們還沒親自執行過這麼長的連續編輯，因此無法確認 100 輪這個數字。請記得，每一輪都是新的任務，也會收取參考圖費用。

如何取得透明 PNG？

將 background 設為 transparent，並保持 output_format 為 png。可只提供提示詞，也可使用參考圖：

task_id = submit({
    "model": "seedream-5-5",
    "prompt": "A glossy red enamel pin shaped like a cherry, product cutout",
    "background": "transparent",
    "size": "1K",
})

transparent 與 jpeg 的組合會在任務建立前被拒絕，因為 JPEG 沒有 alpha 色版。ByteDance 將這項能力描述為原生 RGBA 輸出，支援全透明與半透明，並精細算繪邊緣，因此素材不需另外去背。^[1]

如何透過 API 將影像分解為圖層？

傳入且僅傳入一張影像，並設定 layer_decomposition: true。我們的第三次測試開啟文字辨識，將爵士樂海報分解為最多四張影像：

task_id = submit({
    "model": "seedream-5-5",
    "image": "https://static.seedrouter.ai/media/landing/models/seedream-5-5/v1/poster-source.webp",
    "layer_decomposition": True,
    "size": "1K",
    "layer_decomposition_options": {"max_images": 4, "text_recognition": True},
})

耗時 39 秒，回傳四張影像：底圖與三個透明圖層。

兩個文字圖層都附上辨識出的文字。標題圖層的 text_recognition 包含 "BLUE TIDE\nSESSIONS"，字型推測為 HTF Didot，顏色為 #122C4D；活動資訊圖層則包含 "LIVE JAZZ · PIER 7 HALL · SATURDAY 9 PM"。每行都有自己的邊界框與樣式，讓你能用自己的字型在相同位置重新輸入文字。

使用結果前，有三點要先了解：

• 圖層檔案的尺寸大於邊界框。 每個圖層的放大倍數不同：標題為 1.74×、插畫為 1.08×、活動資訊為 2.59×。放置前，先將每張 PNG 縮放至 bounding_box.absolute 對應的尺寸，再依 z_index 遞增順序堆疊圖層。
• max_images 是數量上限，上限太低會合併元素。 只有四張影像的名額時，模型將薩克斯風演奏者、海浪與珊瑚色太陽放進同一個圖層。請為預期的元素數量留出空間。
• 同一個元素可能出現兩次。 珊瑚色太陽既在插畫圖層裡，也留在底圖上。移動圖層前請先檢查底圖。

Seedream 5.5 API 如何計費？

依每張影像各自的尺寸逐張計費，每張參考圖另行收費。不超過 261 萬像素的影像（1K 與 1.5K）採較低價格級距；2K 與更大尺寸採較高價格級距。圖層分解依底圖與各圖層各自的尺寸計費。失敗的任務不收費。

我們於 2026 年 11 月 10 日執行了三次測試，各次的計費項目如下：

將這些數量乘以上表對應的價格，即可算出費用。圖層分解尤其要留意：這次按四張影像收費，而非一張，因為底圖與每個圖層都會計費。

圖層分解執行期間預留的餘額會高於實際費用。任務受理時，會預留 max_images 張影像所需的餘額，省略時按 30 張計算，auto 採較高價格級距。任務完成後，按實際回傳的影像扣款，再釋回剩餘金額。因此，未提供 max_images 與 size 的分解請求，即使只回傳四張影像，也需要足夠支付 30 張較高價格級距影像加一張輸入影像的餘額才能開始。像我們的第三次測試（請求四張，回傳四張）一樣，將 max_images 設定為接近預期元素數量的值並選擇級距，預留金額就會與帳單金額相近。

需要預先處理哪些錯誤？

參考圖必須是公開的 HTTP(S) URL。不接受 Base64 data URI，因此請先將檔案上傳至自己的儲存空間。支援 JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC 與 HEIF，每張不超過 30 MB。完整錯誤碼清單請見錯誤碼目錄。

常見問題

有 Seedream 5.5 Pro 嗎？

目前還沒有。ByteDance 的發布文章寫道："A Pro version of the Seedream 5.5 series will follow"（該系列之後會推出 Pro 版本），但沒有提供日期。^[1] 目前 API 只有一個模型，即 seedream-5-5。上一代的 Pro 模型仍以 Seedream 5.0 Pro 提供。

Seedream 5.5 API 免費嗎？

不免費。費用從預付餘額逐張扣款，不需訂閱。新帳戶的少量免費餘額足夠生成幾張 1K 影像，你可以先執行上面的指令碼，再決定是否儲值。

可以下載 Seedream 5.5 嗎？

不行。ByteDance 尚未發布模型權重，因此沒有能在本機執行的模型檔案。你需要透過這樣的 API 使用它。

最多可以傳送幾張參考圖？

image 最多接受 10 張。圖層分解則僅接受一張。

一次請求要多久？

我們的三次測試耗時 39 至 47 秒。回傳許多圖層的分解可能需要幾分鐘，因此上面的指令碼最多會輪詢 15 分鐘。

參考資料

1. ByteDance Seed。More Realistic Images, More Stable Editing Across 100 Rounds | Introducing Seedream 5.5。2026 年 11 月 9 日發布。於 2026 年 11 月 11 日查閱 seed.bytedance.com。
2. SeedRouter。Seedream 5.5 API 參考文件。/docs/seedream-5-5。