GPT圖像2.5 API指南：使用Sunburst和Flare生成與編輯圖像

使用 Image API 進行直接的單步生成和編輯。當圖像創建屬於對話或多步驟流程時，使用 Responses API。在 Image API 中，直接選擇 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。

先選擇介面

圖片API提供了生成和編輯端點。回應API支援作為工具的迭代圖片生成，並能將圖片輸入和輸出保持在上下文中。這項架構決策比SDK語法更為重要。

最小生成模式

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();
const result = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "一個簡潔的設計插畫，描繪一座太陽能圖書館，無文字元素"
  size: "1536x1024",
  quality: "中等",
  output_format: "png"
});

fs.writeFileSync("library.png", Buffer.from(result.data[0].b64_json, "base64"));

將API金鑰保存在伺服器端，並遠離原始碼控制。

輸出控制

兩個模型均支援從自動到最高品質、官方限制內的自訂尺寸、PNG/JPEG/WebP格式、JPEG/WebP壓縮，以及透明或不透明背景。如需Alpha通道，請使用PNG或WebP格式。

編輯模式

使用一張或多張圖片調用編輯端點，並提供一個將更改與保留細節分開的提示。在發送前驗證輸入類型和大小。為每個參考賦予一個角色。

生產驗證

儲存請求ID、模型或快照、提示版本、大小、品質、輸出格式、參考資訊、延遲和接受結果。僅重試瞬時故障；在不更改請求的情況下，不要自動重試語義錯誤的輸出。

模型路由

將日常任務路由到Flare，將高精度任務路由到Sunburst。使用固定基準，避免假設更快的模型更便宜，因為當前令牌費率相匹配。

錯誤處理

處理身份驗證、組織驗證、速率限制、無效尺寸、內容審核和空輸出。對符合條件的瞬時錯誤使用帶抖動的指數退避策略，並限制重試次數。切勿不必要地記錄私人圖像數據。

下游動畫

解碼並批准圖像後，儲存來源資訊並將資產傳遞給下游工作流程。當靜態圖像需要變成以角色為主導的故事板、影片或編輯動畫時，Elser AI 是相關的。請在即時產品中驗證支援的上傳和模型選項。

生成端點與編輯端點

使用文本生成新圖像時使用生成功能。當一張或多張現有圖像定義了主體或初始狀態時，使用編輯功能。對於多參考編輯，請按穩定順序發送輸入，並在提示中標識該順序。在請求前驗證檔案類型和尺寸，以便錯誤輸入在本地失敗。

用於迭代工作的響應 API

當用戶創建圖像、以對話方式評估圖像並請求後續更改時，Responses API 非常有用。圖像生成工具可以參與更大的回應流程，並且圖像檔案 ID 可以保留在上下文中。這減少了應用端的拼接工作，但產品仍然需要明確的狀態和版本控制。「和之前一樣」不足以作為關鍵約束條件；請重新表述。

更安全的應用程式架構

保持客戶端、任務佇列、資產儲存與中繼資料儲存彼此獨立。客戶端提交一份簡要說明。伺服器驗證該說明並建立一個任務。工作進程呼叫 OpenAI，解碼結果並將其儲存在生成的資產 ID 下。中繼資料記錄模型快照、提示詞、設定、引用與審核結果。客戶端收到一個短期有效的資產 URL，而非原始憑證。

長時間運行的呼叫不應佔用脆弱的瀏覽器請求。複雜提示可能需要大量時間，因此應展示待處理、已完成和失敗的狀態。使任務提交具有冪等性，以避免客戶端重試時產生重複費用。

驗證規則

檢查自訂尺寸是否滿足文件規定的16的倍數、邊緣、比例及總像素限制。背景透明時要求使用PNG或WebP格式。將壓縮值限制在支援範圍內。僅允許已知的品質和模型參數。在API呼叫前拒絕缺少提示詞的情況。

可靠性與可觀測性

記錄請求ID、HTTP狀態、錯誤類別、嘗試次數和延遲，不記錄私有映像或機密資訊。使用帶抖動的指數退避重試速率限制和符合條件的伺服器錯誤。不要原樣重試身份驗證、無效參數或策略錯誤。對嘗試次數設定上限，並返回有用的產品訊息。

螢幕：

成功率和接受圖像率。
按模型和質量劃分的 p50 和 p95 延遲。
輸入和輸出令牌。
重試和重複任務。
審核結果。
儲存和傳送失敗。

安全與權利

將API金鑰儲存在伺服器端金鑰管理器中。對來源圖像和生成的圖像實施存取控制。設定保留規則，移除不應暴露的元資料，並記錄使用者對上傳材料的權利。OpenAI指出，存取GPT圖像模型可能需要進行組織驗證；請將其作為入職前提條件處理，而非執行時意外。

快照策略

使用未標示日期的 ID 以獲取持續的模型更新。當可重複性更為重要時，固定一個帶日期的快照。在變更生產流量之前，使用相同的基準評估新快照。儲存每個資產返回或配置的實際模型識別碼。

如果啟動文章中包含程式碼，請在其旁邊顯示帶有日期的驗證日期。讀者應理解，模型的可用性、SDK 語法、速率限制和組織要求可能會獨立於文章的概念架構發生變化。

類型化請求契約

即使圖像模型本身不提供結構化輸出，也要定義一個內部模式。一項任務可能包含prompt（提示詞）、workflow（工作流程）、model（模型）、quality（品質）、width（寬度）、height（高度）、format（格式）、background（背景）、compression（壓縮）、參考資源ID以及一個冪等鍵。在轉換為SDK呼叫之前對其進行驗證。

不要從瀏覽器暴露任意的模型名稱或檔案路徑。應將客戶端可見的少量選項對應到伺服器認可的值。透過受存取控制的資產ID解析參照，並驗證目前使用者是否有權讀取這些資產。

編輯請求草圖

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();

const result = await client.images.edit({
  model: "gpt-image-2.5-sunburst",
  image: [fs.createReadStream("approved-character.png")],
  prompt: `只將外套改為深綠色羊毛。
保留面部、頭髮、眼睛顏色、姿勢、手部、構圖和背景。
不要添加文字、珠寶或其他人。
  size: "1024x1536",
  quality: "高",
  output_format: "png"
});

const bytes = Buffer.from(result.data[0].b64_json, "base64");
fs.writeFileSync("character-green-coat.png", bytes);

確切的SDK介面可能會演變，因此在部署前請對照當前官方指南驗證範例。生產程式碼應負責任地串流處理或緩衝，驗證回應是否存在，並原子化儲存，而不是假設每次呼叫都回傳可用資料。

冪等性與重複成本

使用者雙擊或網路重試可能導致同一個昂貴的生成任務被提交兩次。在建立任務時分配一個冪等鍵，在分發前持久化任務，當相同鍵再次出現時回傳既有任務。工作進程應僅取得一次任務並記錄最終狀態。

如果你有意生成多個變體，請將其表示為明確的產品操作，而非意外的重試。圖像API在文件中支援透過n參數生成多張圖像，但你的成本和審核模型應統計每一次輸出。

審核與失敗用戶體驗

所有提示詞和圖像均需經過安全過濾。避免透露敏感的內部審核細節，但應給予用戶足夠的指導以修改合法請求。將政策拒絕與無效設定、授權、速率限制及臨時服務故障區分開來。

當Sunburst不可用時，切勿靜默替換為其他模型，這可能違反品質或合約約定。應返回明確的狀態，或僅在產品已揭露並記錄該行為的情況下使用備用方案。

資產儲存與交付

在記憶體中解碼base64並設定大小限制，驗證聲明的格式，產生校驗和並儲存不可變的原始檔案。單獨產生縮圖。透過短期有效的簽名URL和適當的內容類型提供服務。保留透明PNG/WebP的Alpha通道，避免有損轉換破壞可交付成果。

以適當的存取控制儲存提示和參考資料，以匹配其敏感程度。定義保留和刪除行為。沒有來源的生成檔案難以稽核、複現或安全地交給Elser動畫專案。

發佈前檢查清單

帳戶與組織存取權限已確認。
API 金鑰是伺服器端且可輪換的。
模型ID和維度規則已列入白名單。
作業提交是冪等的。
重試次數有限且分類。
使用情況、延遲和接受度受到監控。
圖像和元數據具有保留規則。
對於身份、品牌和文字敏感的輸出，存在人工審核。
已記錄一份帶日期的快照策略和回滾路徑。

常見問題解答

我應該選擇哪個 API？

Image API 用於直接生成/編輯；Responses API 用於對話式或多步驟圖像體驗。

我可以請求多張圖片嗎？

Image API 在文件中支援用於多個輸出的 n 參數。

API 是否回傳一個 URL？

當前指南展示了圖像API的base64編碼圖像數據；請解碼並安全儲存。

結論

可靠的整合將清晰的模型路由與嚴格的驗證、可觀測性及資產審查相結合。先建立最小的直接請求，僅在核心影像路徑可靠時，再添加對話狀態或後續動畫。