GPT Image 2.5 Sunburst API 接入指南
先看結論 · GPT Image 2.5 Sunburst 在 MaxAPI 使用 openai/gpt-image-2.5-sunburst，可接入文生圖與參考圖編輯。本目錄項目配置最多 16 張參考圖，公開路由為 mix、official、official-cheap。參考圖能否被接受、路由權限與輸出選項，仍需按實際使用的路由確認。
接入規則核對 ·
依 MaxAPI 公開目錄、網關實作與本地回歸案例核對。共用網關核驗不代表已逐個模型進行端到端測試。這是接入參考，不是上游即時可用性或效能報告。
接入前必讀
以下參數依據 MaxAPI 公開配置；所選路由可能另有輸入或權限要求。
- 請求模型 ID
openai/gpt-image-2.5-sunburst- 輸出類型
- 圖片
- Base URL
https://api.maxapi.dev- 生成方式
- 同步回傳或非同步任務
- 參考圖片・本站配置上限
- 16
- 品質參數
high / auto / medium / low / xhigh / max- 解析度與尺寸
- size 使用 WIDTHxHEIGHT。4K 橫向可使用 3840x2160；4K 不代表 4096x4096。
GPT Image 2.5：n=1；邊長須為 16 的倍數且不超過 3840px，總像素 655,360–8,294,400，長寬比介於 1:3 與 3:1。
參考素材必須是真實圖片，不可使用 HTML 錯誤頁、PDF 或只改副檔名的檔案。請確認檔案完整且可解碼；檔案體積小，也可能有過大的像素尺寸。先測通單張參考圖，再增加至完整組合。
模型特點與選型
重視局部改動與細節保留
OpenAI 明確將 Sunburst 的重點放在編輯精確度。它接受文字和圖片，並在常用品質選項外提供 xhigh、max。這是供應商定位，不是 MaxAPI 實測準確率。
資料核對 ·
此模型的資料來源: OpenAI · gpt-image-2.5-sunburst
何時值得選擇它
已核准的畫面只需受控修改時，優先把它納入比較，例如包裝、材質、短標籤或局部在地化。大量探索概念方向時，則可另外比較 Flare。
限制與注意事項
精細編輯不等於像素鎖定。必須列出不可改的區域並逐項驗收；實際品質參數以本站清單和路由行為為準，不能直接照搬官方直連 API 的全部選項。
供應商能力描述的是模型本身，不等於 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、official-cheap。圖片／影片 JSON 請求可指定 route_mode；Gemini 原生請求使用 X-MaxAPI-Route-Mode。路由代表接入與計費選擇，不是另一個公開模型 ID。
| 路由 | 公開基礎價格 | 計費單位 |
|---|---|---|
mix | $0.018 | 每次呼叫 |
official | $4.5 | Uncached text input · 每百萬 Token |
official | $1.125 | Cached text input · 每百萬 Token |
official | $7.2 | Uncached image input · 每百萬 Token |
official | $1.8 | Cached image input · 每百萬 Token |
official | $27 | Image output · 每百萬 Token |
official-cheap | $3.308823 | Uncached text input · 每百萬 Token |
official-cheap | $0.827205 | Cached text input · 每百萬 Token |
official-cheap | $5.294117 | Uncached image input · 每百萬 Token |
official-cheap | $1.323529 | Cached image input · 每百萬 Token |
official-cheap | $19.852941 | Image output · 每百萬 Token |
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": "openai/gpt-image-2.5-sunburst",
"prompt": "a clean product photo of a glass cube",
"route_mode": "mix",
"size": "1024x1024",
"quality": "high",
"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=openai/gpt-image-2.5-sunburst" \
-F 'prompt=Keep the product unchanged and replace the background with a soft gray studio backdrop.' \
-F 'image=@reference.png' \
-F 'size=1024x1024'任務受理成功，不等於圖片已完成
在 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": "openai/gpt-image-2.5-sunburst",
"poll_url": "/v1/images/generations/example-task-id"
}第一次呼叫的驗收清單
請求合約核對 ·
依公開目錄與網關程式核對；範例只說明資料結構，不是付費模型實測、延遲測量，也不保證每條路由目前可用。
先確認請求欄位
model- 此 MaxAPI 入口使用 openai/gpt-image-2.5-sunburst；模型 ID 本身不能決定計費路由。
size / quality / n- 先用 1024x1024、quality=high、n=1。放大輸出時使用此入口支援的尺寸；4K 名稱不代表應傳 4096x4096。
/v1/images/edits- 編輯請用上方 multipart 範例、可解碼圖片與非空提示詞。目錄上限為 16 張參考圖，但這不代表每條路由都已測通上限。
quality / route_mode- 此入口列出 high、auto、medium、low、xhigh、max。範例要求 mix，但已設定的 Key 路由列表仍優先。提高品質前先比較可用結果與實際消耗，品質名稱不是延遲保證。
再確認實際結果
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 生成的概念配圖，並非此模型的實測成果或效果評測。下方提示詞供起步參考，不代表能重現配圖。
創作實踐・共通製作建議
讓商品成為畫面主角，而不只是換個背景
商品視覺不只是「幫我做一張好看的圖」。使用 GPT Image 2.5 Sunburst 前，先說明圖片放在哪裡：商品列表需要清楚辨識主體，官網橫幅需要標題留白，社群直式圖則要考慮手機上的視覺焦點。用途不同，主體比例、鏡頭角度和背景密度也應不同。提示詞再補上材質、光線方向與拍攝距離，讓整張圖有一致的攝影語言。
若是真實商品，應提供清晰參考圖，並列出瓶身形狀、配色、標誌位置等不能改動的細節，再另外描述可以變更的環境。不要讓模型靠想像補出產品包裝或賣點。系列素材可沿用同一份需求，每次只換背景、光線或道具；完成後回到實際展示尺寸，檢查小字、邊緣與商品特徵，而不只看縮圖是否吸引人。
每張參考圖，都應該有自己的任務
MaxAPI 此模型項目配置最多 16 張參考圖，但上限不是每次都要用滿的目標。一張清楚的主體圖，加上一張有用的構圖圖，往往比互不相關的素材更容易說明需求。請依上傳順序標記「圖 1 保留商品」「圖 2 參考構圖」「圖 3 只參考色調」，避免把人物、產品與風格資訊混在一起，讓模型自行猜測。
編輯需求最好分成兩段：必須保留什麼，以及允許修改什麼。例如保留瓶身比例、按壓頭與輪廓，只替換背景，且不要複製風格參考圖裡的標誌或道具。若第一輪結果偏離，先減少素材、釐清衝突，再逐步補圖；不要只靠增加圖片數量解決問題。多圖输入不代表角色或商品一定完全一致，交付前仍應逐張核對。
先探索視覺語言，再投入最終製作
第一張圖最重要的任務，是回答一個具體問題：構圖有沒有成立、配色是否符合品牌、材質看起來是否合適。與其堆疊「高級、震撼、電影感」等形容詞，不如說清楚透明玻璃、織物和金屬之間的關係，交代對比、透視與視覺焦點。將有潛力的方向連同提示詞保存，下一輪才有明確起點，而不是每次都重新抽卡。
海報與編輯版面可以先生成視覺底圖，保留文字安全區，再指定確實需要出現在畫面中的短標題。涉及精確售價、條款或細密排版時，後續在設計工具完成更容易校對；AI 圖片可以是創作的基礎，不必一次包辦全部交付。最後再分別檢查橫幅、方形與直式裁切，避免同一張圖換個尺寸就切掉產品或主要資訊。
可以直接改寫的提示詞範例
好的提示詞是一份小型創作需求：主體是什麼、要做什麼、哪些不能改。將範例換成自己的素材與用途；尺寸、路由和品質仍應在 API 參數指定，不要只寫在文字裡。
01 / 只改瓶蓋，保留包裝
編輯圖 1：只把亮黑色瓶蓋改成拉絲銀色。保留瓶身、標籤文字、標誌位置、液體顏色、背景、陰影方向和鏡頭位置。新瓶蓋的反射要符合原本光線。不要重新設計商品，也不要修飾無關區域。生成後檢查 · 檢查瓶蓋交界，並將所有應保留區域與原圖比較。
先決定交付版型，再決定解析度
圖片要放在哪裡，會直接決定構圖。方形商品圖、橫向官網橫幅與直式封面，需要不同的焦點和安全區。應先選目標長寬比，再安排主體；把成品直接裁成另一種比例，可能切掉商品，或把原本預留給標題的空間吃掉。
請使用上方列出的尺寸控制方式。解析度名稱不等於固定的正方形像素，檔案更大也不代表視覺一定更好。回傳後應查看實際像素尺寸，再以最终展示大小檢查細節與裁切。如果交付要求包含精確網格、法規文字或像素級排版，請保留設計工具的後製步驟。
從參考素材到可交付圖片
整理素材，從必要的幾張開始
刪除重複或無關素材，為每張圖註明角色。確認圖片能完整解碼、商品細節看得清楚，也確認自己有權使用素材。不要把與任務無關的機密圖片一起傳入；素材管理應從第一次測試就開始。
分開管理創作要求與 API 參數
提示詞負責主體、修改內容與限制；model、route_mode、品質和尺寸則使用對應欄位。先用單張圖測通，再逐步增加組合。評估視覺需求時固定正式準備使用的路由，才不會把渠道差異誤判成提示詞變化。
先驗構圖，再做目標尺寸輸出
先檢查主體辨識、透視與留白，再一次調整一個變數並保存結果。切換解析度可能改變細節或構圖，不能把新一輪生成當成前一張草稿的精確放大。選定目標尺寸後仍需重新驗收，不要跳過最後一道品質檢查。
把成品和生成條件一起保存
成品應連同提示詞版本、模型 ID、路由、尺寸與請求 ID 一起保存，另外記錄實際積分消耗和是否通過驗收。這樣團隊取得的是能繼續使用的製作模板，而不是一张無法追溯來源的圖片；流程可重用，但不承諾下一次生成像素完全一致。
依任務選模型，而不只看名字
以下是選型測試方向，並非實測排名。參考圖上限取自本站目錄，個別路由可能另有限制。請使用相同素材、輸出設定與驗收標準比較，不要只比較名稱或單次價格。
| 模型 | 本站參考圖上限 | 建議比較的重點 |
|---|---|---|
| GPT Image 2 | 16 | 文生圖與編輯：比較指令遵循、素材接受度與實際尺寸。 |
| GPT Image 2.5 Sunburst | 16 | 精細編輯：比較修改指令與必須保留細節的落實程度。 |
| GPT Image 2.5 Flare | 16 | 日常創作迭代：用真實需求比較可用品質與完成時間。 |
| Nanobanana Pro | 14 | 參考圖工作流：比較主體細節、構圖與目標輸出檔位。 |
| Gemini 3.1 Flash Image Preview | 14 | 多種輸出檔位：比較版型適配與可用成果成本。 |
從測試到正式接入
測試實際準備使用的路由
首次比較時固定模型、路由與參數。除了常用素材，也測試大檔與特殊輸入。模型公開能力不代表每個上游渠道都能接受所有邊界情況。
區分限流與生成錯誤
遇到 429 時降低請求速率或並發，退避後再試；輸入無效應先修正素材。排查時保存請求與任務 ID，勿把 API Key 或敏感參考素材寫入公開日誌。
追蹤可用結果與實際消耗
以帳戶用量與帳務記錄確認最終結果與消耗。HTTP 成功回應可能只是任務受理，並非最終輸出。正式發布前，請檢查生成文字、視覺細節與參考素材使用權。
已核驗的接入案例
依 MaxAPI 公開目錄、網關實作與本地回歸案例核對。共用網關核驗不代表已逐個模型進行端到端測試。這是接入參考，不是上游即時可用性或效能報告。
多個 Key 共用使用者上限
本地回歸・通過- 驗證條件
- 使用同帳戶的兩個 Key，在記憶體測試限流器中設定較小的使用者額度。
- 實際驗證結果
- 兩個 Key 的請求消耗相同使用者額度，超出後被限流；Key 額度較大不能覆蓋使用者上限，較小的 Key 額度仍有效。
編輯缺少提示詞，會提前拒絕
本地回歸・通過- 驗證條件
- 向本地測試處理器傳入 prompt 為空、含參考圖網址的圖片編輯請求。
- 實際驗證結果
- 路由派送前回傳 HTTP 400、error.code=prompt_required。上傳參考圖不能代替編輯指令。
JSON 參考圖網址可轉換為編輯輸入
本地回歸・通過- 驗證條件
- 將 image_url 與 prompt 傳入本地 JSON 轉 multipart 的轉換器，另測 image_url=not-a-url。
- 實際驗證結果
- 轉換器保留模型與參考欄位，不合法網址語法被拒絕。這驗證的是請求格式，不是素材下載成功或模型出圖成功。
內容拒絕與容量不足分開回報
本地回歸・通過- 驗證條件
- 將模擬的上游內容拒絕與 429／503／504 回應傳入生成錯誤映射器。
- 實際驗證結果
- 內容拒絕映射為 451；容量不足、暫不可用、逾時保留不同公開錯誤碼。本組相容格式的 429／503 驗證回應帶 Retry-After: 2。
圖片預留餘額依終態結算或釋放
本地回歸・通過- 驗證條件
- 在本地測試資料庫中，分別執行同步圖片預留餘額的成功與失敗流程。
- 實際驗證結果
- 成功時使用預留額度並產生用量記錄；失敗時釋放預留、不收生成費。此結果驗證受測程式流程，不是任何線上帳戶的即時餘額。
4K 名稱不能繞過像素上限
本地回歸・通過- 驗證條件
- 先驗證 3840x2160，再向本地 Sunburst 與 Flare 生成／編輯處理器傳入 3840x2560。
- 實際驗證結果
- 3840x2160 通過尺寸校驗；3840x2560 超過 8,294,400 像素，路由前回傳 400。通過本站校驗不代表所有上游都接受該尺寸。
不把請求品質冒充為實際回傳品質
本地回歸・通過- 驗證條件
- 請求 high，模擬回應為 quality=medium、size=3520x2336、usage.source=estimated。
- 實際驗證結果
- 回應整理流程保留這些回傳值，不補造缺失用量。請核對回應 metadata 與實際檔案，不要把請求的檔位直接當成已交付品質。
常見問題
什麼情況應選擇此模型？
已核准的畫面只需受控修改時，優先把它納入比較，例如包裝、材質、短標籤或局部在地化。大量探索概念方向時，則可另外比較 Flare。
此模型入口有哪些特別需要注意的限制？
精細編輯不等於像素鎖定。必須列出不可改的區域並逐項驗收；實際品質參數以本站清單和路由行為為準，不能直接照搬官方直連 API 的全部選項。
為什麼改了 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 不是繞過限制的方法。
這些本地回歸案例能證明線上模型效能嗎？
本地測試使用模擬請求、回應與測試儲存，不呼叫付費模型渠道。它們驗證請求處理，不驗證模型畫質、線上成功率、延遲，也不代表參考圖上限已端到端測通。頁面其他位置的概念配圖，不是這些測試的輸出。
GPT Image 2.5 Sunburst 應填哪個模型 ID？
使用 openai/gpt-image-2.5-sunburst。請依範例的端點格式傳入；Gemini 原生網址使用短模型名稱。
頁面價格適用所有帳戶和路由嗎？
1 積分 = 1 美元。此處為目錄基礎價格，並非帳戶即時報價；最終消耗依帳戶倍率與生效計費配置結算。Token 單價不等於每張圖片固定價格。
失敗請求會扣積分嗎？
MaxAPI 公開規則為失敗請求不計費。處理期間可能暫時預留餘額，請以任務最終結果與帳務記錄核對，不要將暫時餘額變動當作最終消耗。
為什麼我的 API Key 不能使用某條路由？
路由是否可用，取決於模型、帳戶權限與 API Key 允許的路由。公開列出價格不代表已取得權限；修改 route_mode 前請先確認帳戶和金鑰配置。
參考圖為什麼會驗證失敗？
參考素材必須是真實圖片，不可使用 HTML 錯誤頁、PDF 或只改副檔名的檔案。請確認檔案完整且可解碼；檔案體積小，也可能有過大的像素尺寸。先測通單張參考圖，再增加至完整組合。
4K 一定是 4096×4096 嗎？
不是。解析度檔位不是通用的像素尺寸。size 使用 WIDTHxHEIGHT。4K 橫向可使用 3840x2160；4K 不代表 4096x4096。 請以實際輸出尺寸安排版面。
失敗或逾時後要立即重試嗎？
先分辨是限流、輸入錯誤，還是任務仍在執行。已有任務 ID 時，先查狀態再決定是否重新生成。僅對可重試錯誤使用有次數限制的退避重試。