GPT Image 2.5

GPT Image 2.5 接受文字提示詞和選用的參考影像。提交一次，保留回傳的任務 ID，然後查詢該任務以取得生成完成的影像。它提供兩個讀取相同參數的模型：Flare 適合日常工作，Sunburst 適合最重視編輯精準度的情境。

模型 ID

四個 ID 接受相同的參數。兩個通道的差別在於計費；目前價格見模型頁。

快速範例

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "An amber glass bottle on a cream background, studio lighting",
    "size": "1024x1024",
    "quality": "low"
  }'

端點

POST https://api.seedrouter.ai/v1/images/generations

生成、參考影像編輯和遮罩編輯都使用同一個端點。回應中包含的是任務 ID，而不是生成完成的影像。請把 API 金鑰保存在伺服器端程式碼中。

參數

尺寸規則

常用取值為 1024x1024、1536x1024 和 1024x1536。自訂尺寸必須同時滿足以下全部規則：

• 寬和高都是 16 的倍數。
• 任一邊長都不超過 3840 像素。
• 長寬比介於 1:3 到 3:1 之間。
• 總面積介於 655,360 到 8,294,400 像素之間（含端點）。

auto 表示由模型決定輸出尺寸。不要把 16:9 這類長寬比作為 size 傳入。

Playground 提供 Auto、比例和自訂三種控制項。比例模式把長寬比與 1K、2K 或 4K 的像素預算預設組合起來，最終只提交換算後的 size。這些只是介面預設，不是獨立的 API 參數：不要傳 resolution 或 aspect_ratio。例如 16:9 + 4K 提交 size: "3840x2160"；9:16 + 4K 提交 "2160x3840"；1:1 + 2K 提交 "2048x2048"。取整和邊長上限可能使所選等級的實際像素數變少。提交前會顯示確切的尺寸。

OpenAI 將高於 2560×1440 的解析度描述為實驗性質。在上述限制範圍內它們會被接受；但更高的解析度並不保證更好的細節。

品質等級

xhigh 和 max 是 GPT Image 2.5 新增的等級；GPT Image 2 最高只到 high。等級越高，算繪時間越長，在按 token 計費的 ID 上也會消耗更多輸出 token。在 1024x1024 下實測，單次算繪在 low、medium、high、xhigh 和 max 下分別回報 196、439、1,756、3,122 和 7,024 個輸出 token。這些是觀測樣本，不是保證值：用量也取決於尺寸和內容。

草稿階段請使用 low，先比較結果再決定是否提高等級。auto 由模型自行選擇，它並不保證特定的等級或費用。

透明背景

GPT Image 2.5 支援透明背景。需要透明背景時，請設定 background: "transparent" 並使用 PNG。JPEG 不支援透明。壓縮僅對 JPEG 生效。

user 可用於 API 整合，但不會在 Playground 中顯示，也不會自動填入。

選用的純量設定（n、size、quality、background、output_format、output_compression、moderation）接受 null 表示省略。未知欄位會被拒絕。input_fidelity 不是 GPT Image 2.5 的參數。style 和 response_format 屬於其他影像模型，此處不接受。

模式

沒有獨立的模式參數，也沒有另一個編輯端點需要選擇。

編輯參考影像

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Make the bottle blue. Preserve the composition and lighting.",
    "images": [{"image_url": "https://example.com/reference.png"}],
    "mask": {"image_url": "https://example.com/mask.png"},
    "output_format": "jpeg",
    "output_compression": 90
  }'

請把範例中的兩個 URL 換成你自己、可存取的影像。若不需要指定編輯區域，省略 mask 即為參考影像編輯。

媒體輸入

本 API 只接受 URL 參考。不接受 OpenAI Files ID、base64 data URL 和 multipart 上傳。Playground 會先把所選檔案上傳到儲存空間，再提交其 URL。

參考影像必須是可公開存取的 HTTP(S) URL，指向 PNG、JPEG 或 WebP 檔案，單一檔案小於 50 MB。遮罩必須是小於 4 MB 的 PNG，尺寸與第一張參考影像相同；其透明區域標記要編輯的部分。遮罩只是對模型的引導，並不保證像素級精確的邊界。傳入多張參考影像時，遮罩作用於第一張。URL 媒體在處理過程中才會驗證；無效或無法存取的媒體可能導致任務失敗。

Playground 會上傳所選檔案並提交其 URL。API 請求使用 JSON 形式的 URL 物件：不要傳送檔案位元組、base64、data: URL、blob: URL 或 multipart 表單資料。

計費維度

目前費率請查看模型定價區段。Standard ID 每交付一張圖收一個固定價，與品質、尺寸和提示詞無關。Official ID 的最終費用取決於輸入和輸出的用量：品質、輸出尺寸、參考影像、提示詞長度和出圖數量都會影響它。

Playground 的預估以實測樣本和目前費率為基礎，不構成保證報價。最終扣款請在帳號的用量記錄中查看。失敗的任務不計費。

輸出結構

提交後會回傳一個任務參考：

{
  "id": "task_...",
  "model": "gpt-image-2.5-flare",
  "status": "processing",
  "created_at": 1789970508
}

輪詢任務

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

請以較為節制的間隔輪詢，例如每三秒一次，直到 status 變為 completed 或 failed。輪詢過程中發生網路逾時，並不代表生成失敗：請保留任務 ID 並繼續查詢。不要為了查看進度而再建立一個任務。

完整輪詢範例

請在上方的 Python 提交範例之後執行這段程式碼。它使用回傳的 task_id，最長等待十分鐘。達到這個本地期限只會停止輪詢；請保留 ID 並繼續查詢同一個任務。

import time

print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

已完成的任務

已完成的任務會回傳託管的影像 URL 和用量：

{
  "id": "task_...",
  "model": "gpt-image-2.5-flare",
  "status": "completed",
  "created_at": 1789970508,
  "finished_at": 1789970538,
  "output": {
    "created": 1789970532,
    "data": [{"url": "https://static.seedrouter.ai/media/tasks/task_example/0.png"}],
    "usage": {
      "input_tokens": 29,
      "output_tokens": 196,
      "total_tokens": 225
    }
  }
}

本 API 採用非同步任務交付方式。它不是同步 Images SDK 的替代品；不支援 stream 和 partial_images。

錯誤

在任務建立之前就被拒絕的請求，會回傳 HTTP 錯誤狀態碼和一個 error 物件。受理之後才失敗的任務，查詢時會回傳 HTTP 200，並帶有 status: "failed" 和一個 error 物件。

錯誤碼、HTTP 狀態碼和重試建議請參見共用錯誤目錄。所有模型 API 使用同一套錯誤封裝結構。

{
  "id": "task_...",
  "status": "failed",
  "error": {
    "code": 60002,
    "message": "Generation could not be completed. Please try again."
  }
}

如果提交本身逾時，請先檢查你的任務歷史再重新提交：第一次請求有可能已經被受理。

實用建議

• 在提示詞中描述材質、構圖和光線。
• 進行編輯時，既要說明要改什麼，也要說明哪些應保持不變。
• 只需改動選定區域時，請使用遮罩。
• 需要長期保存時，請把回傳的影像儲存到你自己的儲存空間中。

相關內容

• GPT Image 2.5 Playground 與定價
• 下載 OpenAPI
• 可複製的 Markdown