Seedream 4.0 API 接入指南
先看結論 · Seedream 4.0 在 MaxAPI 使用 bytedance/seedream-4.0，可接入文生圖與參考圖編輯。本目錄項目配置最多 14 張參考圖，公開路由為 mix、official。參考圖能否被接受、路由權限與輸出選項，仍需按實際使用的路由確認。
接入規則核對 ·
依 MaxAPI 公開目錄、網關實作與本地回歸案例核對。共用網關核驗不代表已逐個模型進行端到端測試。這是接入參考，不是上游即時可用性或效能報告。
接入前必讀
以下參數依據 MaxAPI 公開配置；所選路由可能另有輸入或權限要求。
- 請求模型 ID
bytedance/seedream-4.0- 輸出類型
- 圖片
- Base URL
https://api.maxapi.dev- 生成方式
- 同步回傳或非同步任務
- 參考圖片・本站配置上限
- 14
- 解析度與尺寸
- 官方 Replicate：size + aspect_ratio（預設 match_input_image）。4.0：1K/2K/4K/custom；4.5：2K/4K/custom；Lite：2K/3K；Pro：1K/2K，圖層拆分另支援 1.5K/auto。連續出圖參數見 API 表格。
參考素材必須是真實圖片，不可使用 HTML 錯誤頁、PDF 或只改副檔名的檔案。請確認檔案完整且可解碼；檔案體積小，也可能有過大的像素尺寸。先測通單張參考圖，再增加至完整組合。
模型特點與選型
Seedream 4.0：文生圖與參考圖編輯
Seedream 4.0 透過 MaxAPI 圖片端點提供按張計費，已核對渠道的文生圖與參考圖請求。此入口依渠道模型識別碼及實測參數範圍配置。
資料核對 ·
此模型的資料來源: ByteDance · Seedream 4.0
何時值得選擇它
Seedream 4.0 可使用固定提示詞、尺寸與參考順序比較商品圖。Mix 公開基礎價為每張 0.045 積分。
限制與注意事項
官方 Replicate 的完整參數與預設值見 API 分頁。4.0、4.5、Lite 可使用 max_images 連續出圖；Pro 可拆分單張圖片的圖層。支援的安全檢查開關僅供 API Key 使用。其他路由保留既有像素預設（2048x2048 / 4096x4096; Mix: 14 references; Official: 10）與 n=1，不提供遮罩及品質檔位。
供應商能力描述的是模型本身，不等於 MaxAPI 已開通全部功能。本站接入以此入口列出的參數、輸入類型和路由為準；供應商的速度、品質定位不是服務保證。
MaxAPI 實際如何處理請求
究竟使用哪條路由？
路由優先順序為：API Key 已配置的 route_modes 列表 → 請求明確指定的路由 → 模型預設路由。Key 列表非空時，優先於請求中的 route_mode。測試特定路由前，先確認 Key 配置；只修改請求參數，不一定會切換實際使用的路由。
使用者 RPM 由旗下 Key 共同使用
使用者設定的有效 RPM 上限，由旗下 API Key 共同使用。Key 可以設得更嚴格，但 Key 上限高於使用者時，仍不能突破使用者限制。例如使用者 200 RPM，不代表每個 Key 都各有 200 RPM。全站 RPM 與並發控制仍另外生效，增加 Key 不是繞過限制的方法。
路由與價格
公開路由：mix、official。圖片／影片 JSON 請求可指定 route_mode；Gemini 原生請求使用 X-MaxAPI-Route-Mode。路由代表接入與計費選擇，不是另一個公開模型 ID。
| 路由 | 公開基礎價格 | 計費單位 |
|---|---|---|
mix | $0.045 | 每張輸出圖片 |
official | $0.03 | 每張輸出圖片 |
1 積分 = 1 美元。此處為目錄基礎價格，並非帳戶即時報價；最終消耗依帳戶倍率與生效計費配置結算。Token 單價不等於每張圖片固定價格。
查看即時價格第一次呼叫
建立 MaxAPI API Key，並在服務端設定 MAXAPI_KEY，勿放入瀏覽器程式碼。Key 已設定的路由列表優先，即使請求另有指定；列表為空時才採用請求路由，都未指定則使用模型預設。API 呼叫可能產生費用。
POST /v1/images/generationsPOST /v1/images/editsGET /v1/images/generations/{task_id}GET /v1/images/edits/{task_id}
同步呼叫會等待生成結果。非同步圖片生成可在 JSON 內加入 async: true；Gemini 原生請求使用 X-MaxAPI-Async: true。保存回傳任務 ID，再輪詢上方對應的 GET 端點。
curl -X POST "https://api.maxapi.dev/v1/images/generations" \
-H "Authorization: Bearer $MAXAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bytedance/seedream-4.0",
"prompt": "a clean product photo of a glass cube",
"route_mode": "mix",
"size": "2048x2048",
"n": 1
}'參考圖編輯範例
將 reference.png 換成可正常解碼的真實圖片。multipart boundary 由 curl 自動設定，此請求不要加 JSON Content-Type 標頭。
curl "https://api.maxapi.dev/v1/images/edits" \
-H "Authorization: Bearer $MAXAPI_KEY" \
-F "model=bytedance/seedream-4.0" \
-F 'prompt=Keep the product unchanged and replace the background with a soft gray studio backdrop.' \
-F 'image=@reference.png' \
-F 'size=2048x2048'任務受理成功，不等於圖片已完成
在 OpenAI 相容圖片端點中，async=true 會回傳 id、status、poll_url 等任務欄位。使用同帳戶的身分驗證查詢 poll_url；queued／running 不是出圖成功。確認最終狀態後再讀取 data。輪詢 HTTP 200 只代表查詢成功，不代表生成成功。
{
"id": "example-task-id",
"object": "image.generation.task",
"status": "queued",
"model": "bytedance/seedream-4.0",
"poll_url": "/v1/images/generations/example-task-id"
}第一次呼叫的驗收清單
請求合約核對 ·
依公開目錄與網關程式核對；範例只說明資料結構，不是付費模型實測、延遲測量，也不保證每條路由目前可用。
先確認請求欄位
model- 此 MaxAPI 入口使用 bytedance/seedream-4.0；模型 ID 本身不能決定計費路由。
size / n- 先用 size=2048x2048、n=1，不傳 quality、resolution 或 aspect_ratio。Pro 支援 2K，4.0、4.5、5.0 支援 2K/4K；4.0 官方路由最多 10 張參考圖。
/v1/images/edits- 編輯請用上方 multipart 範例、可解碼圖片與非空提示詞。目錄上限為 14 張參考圖，但這不代表每條路由都已測通上限。
再確認實際結果
data[]- 同步結果請檢查 data 項目中的 url 或 b64_json，下載或解碼後核對實際尺寸與畫面細節。
async=true- 非同步請保存 id、poll_url。輪詢 HTTP 200 只表示查詢成功，應等 status=succeeded 並確認 data；不要為了查進度再次 POST。
{
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}先看現象，再判斷錯誤原因
400缺少或不合法的請求欄位
- 如何判斷
- 不要只看 400，請一起看 error.code。圖片編輯缺少提示詞時會出現 prompt_required；參數驗證失敗與上游生成失敗不是同一回事。
- 下一步處理
- 檢查 model、prompt、欄位型別與文件中的尺寸／品質值，修正後再送出。Gemini 原生回應則查看數字型 error.code 與 error.status。
圖片檔案無效參考圖無法解碼或不被接受
- 如何判斷
- 檔名是 .png，不代表內容就是真正的 PNG。素材網址可能回傳錯誤頁、不完整下載，或所選渠道不接受的格式。上游 400 也可能被整理成通用生成失敗，不能只憑最終狀態碼判斷是哪張素材出問題。
- 下一步處理
- 逐張下載並在本地解碼，核對 MIME 類型與像素尺寸；必要時重新匯出成支援格式。先測單張，再依順序增加素材以定位問題。不要對同一份無效檔案原樣反覆重試。
429rate_limit_exceeded / capacity_exhausted
- 如何判斷
- 429 可能來自使用者／Key RPM、全站容量，或生成容量不足。結合 Retry-After 與回傳的 X-RateLimit-*／X-Global-* 標頭判斷；單一狀態碼不能代表唯一原因。
- 下一步處理
- 有 Retry-After 時依其等待，按原因降低發送速率或同時處理數，使用有限次退避重試。全站容量不等於單一帳戶可獨占的額度。
451content_policy_violation
- 如何判斷
- 在圖片生成失敗處理中，識別到的上游內容拒絕會映射為 451，不能當成網路故障。本地審核攔截與上游內容拒絕是不同階段，即使兩者都可能讓請求無法產出。
- 下一步處理
- 依提示檢查內容是否合規；若懷疑誤判，攜帶請求 ID 聯絡支援。不要對原樣被拒內容反覆重試，也不要輪換路由規避審核。
502 / 503 / 504生成失敗、服務暫不可用或逾時
- 如何判斷
- 這些狀態不是同一個意思。相容圖片端點區分 generation_failed、generation_unavailable 與 generation_timeout。客戶端自身逾時時，伺服器上的任務也可能仍在執行。
- 下一步處理
- 已有任務 ID 就先查狀態，不要直接建立第二個任務。没有任務 ID 時，保留請求 ID 與時間，先排查再決定是否重送。暫時性故障只做有限次重試，不使用無限迴圈。
應用場景與工作方式
下方場景與提示詞是本站建議的評估方向，不是供應商評分或實測成果。
AI 生成的概念配圖，並非此模型的實測成果或效果評測。下方提示詞供起步參考，不代表能重現配圖。
創作實踐・共通製作建議
讓商品成為畫面主角，而不只是換個背景
商品視覺不只是「幫我做一張好看的圖」。使用 Seedream 4.0 前，先說明圖片放在哪裡：商品列表需要清楚辨識主體，官網橫幅需要標題留白，社群直式圖則要考慮手機上的視覺焦點。用途不同，主體比例、鏡頭角度和背景密度也應不同。提示詞再補上材質、光線方向與拍攝距離，讓整張圖有一致的攝影語言。
若是真實商品，應提供清晰參考圖，並列出瓶身形狀、配色、標誌位置等不能改動的細節，再另外描述可以變更的環境。不要讓模型靠想像補出產品包裝或賣點。系列素材可沿用同一份需求，每次只換背景、光線或道具；完成後回到實際展示尺寸，檢查小字、邊緣與商品特徵，而不只看縮圖是否吸引人。
每張參考圖，都應該有自己的任務
MaxAPI 此模型項目配置最多 14 張參考圖，但上限不是每次都要用滿的目標。一張清楚的主體圖，加上一張有用的構圖圖，往往比互不相關的素材更容易說明需求。請依上傳順序標記「圖 1 保留商品」「圖 2 參考構圖」「圖 3 只參考色調」，避免把人物、產品與風格資訊混在一起，讓模型自行猜測。
編輯需求最好分成兩段：必須保留什麼，以及允許修改什麼。例如保留瓶身比例、按壓頭與輪廓，只替換背景，且不要複製風格參考圖裡的標誌或道具。若第一輪結果偏離，先減少素材、釐清衝突，再逐步補圖；不要只靠增加圖片數量解決問題。多圖输入不代表角色或商品一定完全一致，交付前仍應逐張核對。
先探索視覺語言，再投入最終製作
第一張圖最重要的任務，是回答一個具體問題：構圖有沒有成立、配色是否符合品牌、材質看起來是否合適。與其堆疊「高級、震撼、電影感」等形容詞，不如說清楚透明玻璃、織物和金屬之間的關係，交代對比、透視與視覺焦點。將有潛力的方向連同提示詞保存，下一輪才有明確起點，而不是每次都重新抽卡。
海報與編輯版面可以先生成視覺底圖，保留文字安全區，再指定確實需要出現在畫面中的短標題。涉及精確售價、條款或細密排版時，後續在設計工具完成更容易校對；AI 圖片可以是創作的基礎，不必一次包辦全部交付。最後再分別檢查橫幅、方形與直式裁切，避免同一張圖換個尺寸就切掉產品或主要資訊。
可以直接改寫的提示詞範例
好的提示詞是一份小型創作需求：主體是什麼、要做什麼、哪些不能改。將範例換成自己的素材與用途；尺寸、路由和品質仍應在 API 參數指定，不要只寫在文字裡。
01 / Seedream 4.0 商品練習
用於 Seedream 4.0 比較：製作藍色陶瓷杯的方形商品圖，白色背景，左側柔光，保留杯把形狀，杯子四周留白，不加文字。生成後檢查 · 檢查形狀、光線及實際輸出尺寸。
先決定交付版型，再決定解析度
圖片要放在哪裡，會直接決定構圖。方形商品圖、橫向官網橫幅與直式封面，需要不同的焦點和安全區。應先選目標長寬比，再安排主體；把成品直接裁成另一種比例，可能切掉商品，或把原本預留給標題的空間吃掉。
請使用上方列出的尺寸控制方式。解析度名稱不等於固定的正方形像素，檔案更大也不代表視覺一定更好。回傳後應查看實際像素尺寸，再以最终展示大小檢查細節與裁切。如果交付要求包含精確網格、法規文字或像素級排版，請保留設計工具的後製步驟。
從參考素材到可交付圖片
整理素材，從必要的幾張開始
刪除重複或無關素材，為每張圖註明角色。確認圖片能完整解碼、商品細節看得清楚，也確認自己有權使用素材。不要把與任務無關的機密圖片一起傳入；素材管理應從第一次測試就開始。
分開管理創作要求與 API 參數
提示詞負責主體、修改內容與限制；model、route_mode、品質和尺寸則使用對應欄位。先用單張圖測通，再逐步增加組合。評估視覺需求時固定正式準備使用的路由，才不會把渠道差異誤判成提示詞變化。
先驗構圖，再做目標尺寸輸出
先檢查主體辨識、透視與留白，再一次調整一個變數並保存結果。切換解析度可能改變細節或構圖，不能把新一輪生成當成前一張草稿的精確放大。選定目標尺寸後仍需重新驗收，不要跳過最後一道品質檢查。
把成品和生成條件一起保存
成品應連同提示詞版本、模型 ID、路由、尺寸與請求 ID 一起保存，另外記錄實際積分消耗和是否通過驗收。這樣團隊取得的是能繼續使用的製作模板，而不是一张無法追溯來源的圖片；流程可重用，但不承諾下一次生成像素完全一致。
依任務選模型，而不只看名字
以下是選型測試方向，並非實測排名。參考圖上限取自本站目錄，個別路由可能另有限制。請使用相同素材、輸出設定與驗收標準比較，不要只比較名稱或單次價格。
| 模型 | 本站參考圖上限 | 建議比較的重點 |
|---|---|---|
| Nanobanana Pro | 14 | 參考圖工作流：比較主體細節、構圖與目標輸出檔位。 |
| Gemini 3.1 Flash Image Preview | 14 | 多種輸出檔位：比較版型適配與可用成果成本。 |
| Gemini 3.1 Flash Lite Image | 3 | 1K 交付需求：驗證細節是否足以支援實際展示位置。 |
| Gemini 2.5 Flash Image | 3 | 預設尺寸工作流：不依賴可選 4K 檔位來驗證構圖。 |
| GPT Image 2 | 16 | 文生圖與編輯：比較指令遵循、素材接受度與實際尺寸。 |
從測試到正式接入
測試實際準備使用的路由
首次比較時固定模型、路由與參數。除了常用素材，也測試大檔與特殊輸入。模型公開能力不代表每個上游渠道都能接受所有邊界情況。
區分限流與生成錯誤
遇到 429 時降低請求速率或並發，退避後再試；輸入無效應先修正素材。排查時保存請求與任務 ID，勿把 API Key 或敏感參考素材寫入公開日誌。
追蹤可用結果與實際消耗
以帳戶用量與帳務記錄確認最終結果與消耗。HTTP 成功回應可能只是任務受理，並非最終輸出。正式發布前，請檢查生成文字、視覺細節與參考素材使用權。
已核驗的接入案例
依 MaxAPI 公開目錄、網關實作與本地回歸案例核對。共用網關核驗不代表已逐個模型進行端到端測試。這是接入參考，不是上游即時可用性或效能報告。
多個 Key 共用使用者上限
本地回歸・通過- 驗證條件
- 使用同帳戶的兩個 Key，在記憶體測試限流器中設定較小的使用者額度。
- 實際驗證結果
- 兩個 Key 的請求消耗相同使用者額度，超出後被限流；Key 額度較大不能覆蓋使用者上限，較小的 Key 額度仍有效。
JSON 參考圖網址可轉換為編輯輸入
本地回歸・通過- 驗證條件
- 將 image_url 與 prompt 傳入本地 JSON 轉 multipart 的轉換器，另測 image_url=not-a-url。
- 實際驗證結果
- 轉換器保留模型與參考欄位，不合法網址語法被拒絕。這驗證的是請求格式，不是素材下載成功或模型出圖成功。
內容拒絕與容量不足分開回報
本地回歸・通過- 驗證條件
- 將模擬的上游內容拒絕與 429／503／504 回應傳入生成錯誤映射器。
- 實際驗證結果
- 內容拒絕映射為 451；容量不足、暫不可用、逾時保留不同公開錯誤碼。本組相容格式的 429／503 驗證回應帶 Retry-After: 2。
圖片預留餘額依終態結算或釋放
本地回歸・通過- 驗證條件
- 在本地測試資料庫中，分別執行同步圖片預留餘額的成功與失敗流程。
- 實際驗證結果
- 成功時使用預留額度並產生用量記錄；失敗時釋放預留、不收生成費。此結果驗證受測程式流程，不是任何線上帳戶的即時餘額。
常見問題
什麼情況應選擇此模型？
Seedream 4.0 可使用固定提示詞、尺寸與參考順序比較商品圖。Mix 公開基礎價為每張 0.045 積分。
此模型入口有哪些特別需要注意的限制？
官方 Replicate 的完整參數與預設值見 API 分頁。4.0、4.5、Lite 可使用 max_images 連續出圖；Pro 可拆分單張圖片的圖層。支援的安全檢查開關僅供 API Key 使用。其他路由保留既有像素預設（2048x2048 / 4096x4096; Mix: 14 references; Official: 10）與 n=1，不提供遮罩及品質檔位。
為什麼改了 route_mode，路由卻沒變？
路由優先順序為：API Key 已配置的 route_modes 列表 → 請求明確指定的路由 → 模型預設路由。Key 列表非空時，優先於請求中的 route_mode。測試特定路由前，先確認 Key 配置；只修改請求參數，不一定會切換實際使用的路由。
每個 API Key 都有完整的使用者 RPM 額度嗎？
使用者設定的有效 RPM 上限，由旗下 API Key 共同使用。Key 可以設得更嚴格，但 Key 上限高於使用者時，仍不能突破使用者限制。例如使用者 200 RPM，不代表每個 Key 都各有 200 RPM。全站 RPM 與並發控制仍另外生效，增加 Key 不是繞過限制的方法。
這些本地回歸案例能證明線上模型效能嗎？
本地測試使用模擬請求、回應與測試儲存，不呼叫付費模型渠道。它們驗證請求處理，不驗證模型畫質、線上成功率、延遲，也不代表參考圖上限已端到端測通。頁面其他位置的概念配圖，不是這些測試的輸出。
Seedream 4.0 應填哪個模型 ID？
使用 bytedance/seedream-4.0。請依範例的端點格式傳入；Gemini 原生網址使用短模型名稱。
頁面價格適用所有帳戶和路由嗎？
1 積分 = 1 美元。此處為目錄基礎價格，並非帳戶即時報價；最終消耗依帳戶倍率與生效計費配置結算。Token 單價不等於每張圖片固定價格。
失敗請求會扣積分嗎？
MaxAPI 公開規則為失敗請求不計費。處理期間可能暫時預留餘額，請以任務最終結果與帳務記錄核對，不要將暫時餘額變動當作最終消耗。
為什麼我的 API Key 不能使用某條路由？
路由是否可用，取決於模型、帳戶權限與 API Key 允許的路由。公開列出價格不代表已取得權限；修改 route_mode 前請先確認帳戶和金鑰配置。
參考圖為什麼會驗證失敗？
參考素材必須是真實圖片，不可使用 HTML 錯誤頁、PDF 或只改副檔名的檔案。請確認檔案完整且可解碼；檔案體積小，也可能有過大的像素尺寸。先測通單張參考圖，再增加至完整組合。
4K 一定是 4096×4096 嗎？
不是。解析度檔位不是通用的像素尺寸。官方 Replicate：size + aspect_ratio（預設 match_input_image）。4.0：1K/2K/4K/custom；4.5：2K/4K/custom；Lite：2K/3K；Pro：1K/2K，圖層拆分另支援 1.5K/auto。連續出圖參數見 API 表格。 請以實際輸出尺寸安排版面。
失敗或逾時後要立即重試嗎？
先分辨是限流、輸入錯誤，還是任務仍在執行。已有任務 ID 時，先查狀態再決定是否重新生成。僅對可重試錯誤使用有次數限制的退避重試。