Claude Opus 5.5 已在 SeedRouter 上線

GPT Image 2.5 API Python 教學:可執行的完整範例

用 Python 和 JavaScript 呼叫 GPT Image 2.5 API,輪詢任務取得影像 URL,用參考圖編輯,並排除模型 ID 與參數錯誤。

以 Markdown 閱讀

要呼叫 GPT Image 2.5 API,請帶上 gpt-image-2.5-flare 這類模型 ID 和提示詞,POST 到 https://api.seedrouter.ai/v1/images/generations,保留回應裡的任務 id,然後輪詢 GET /v1/tasks/{id},直到狀態變成 completed。完成的任務裡就有影像的 URL。文字生成影像、參考圖編輯和遮罩編輯都用同一個端點。

本教學是一條完整、可直接執行的 Python 流程,附上對應的 JavaScript 寫法,最後整理最常遇到的錯誤以及它們各自的意思。

傳送第一個請求前需要準備什麼?

兩樣東西:一把 API Key 和一個模型 ID。

在 API Key 頁面建立 key,並把它存放在伺服器的環境變數裡,絕不要放進瀏覽器端程式碼:

export SEEDROUTER_API_KEY="your-key"

接著從四個 GPT Image 2.5 模型 ID 中選一個。請照原樣複製;不存在不帶等級的 gpt-image-2.5 ID。

模型 ID模型計費方式
gpt-image-2.5-flareFlare每張影像固定價
gpt-image-2.5-sunburstSunburst每張影像固定價
gpt-image-2.5-flare-officialFlaretoken 用量
gpt-image-2.5-sunburst-officialSunbursttoken 用量

如果不確定該從哪個模型開始,就用 Flare;Flare vs Sunburst 說明了什麼時候值得用 Sunburst。

如何用 Python 生成影像?

提交會立即回傳。回應是任務的參照,而不是影像本身。

import os
import requests

response = requests.post(
    "https://api.seedrouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "An amber glass bottle on a cream background, studio lighting",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

在做任何其他事之前,先把 task_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 下載下來,自己儲存。結果 URL 只是交付時的交接,不是長期儲存空間。

同樣的呼叫用 JavaScript 怎麼寫?

請求完全相同,只換了 HTTP 用戶端。請在伺服器上執行,讓 key 永遠不會進到瀏覽器。

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2.5-flare',
    prompt: 'An amber glass bottle on a cream background, studio lighting',
    size: '1024x1024',
    quality: 'low',
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();

用相同的標頭輪詢 GET https://api.seedrouter.ai/v1/tasks/${taskId},做法和 Python 迴圈完全一樣。

如何編輯既有的影像?

在同一個請求裡加上參考圖即可。沒有獨立的編輯端點,也沒有模式欄位:傳送 images 就是編輯,再加上 mask 就能把修改限制在某一塊區域。

{
  "model": "gpt-image-2.5-sunburst",
  "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"}
}

輸入必須是公開的 HTTPS URL。最多可傳送 16 張參考圖,格式為 PNG、JPEG 或 WebP,每張小於 50 MB。遮罩是小於 4 MB 的 PNG,尺寸與第一張參考圖相同,其中透明的區域標示要修改的部分。Base64 字串、data: URL 和檔案上傳都會被拒絕,所以請先把檔案上傳到你自己的儲存空間,再傳送 URL。

為什麼 API 提示模型無法使用?

HTTP 400 搭配錯誤碼 20002(“The requested model is not available.”),代表 model 的值不是 API 提供的 ID。常見原因是差一點點:gpt-image-2.5 沒帶等級、gpt-image-2-5-flare 用連字號取代了小數點,或是 sunburst 打錯字。請從上面的表格複製 ID。

參數錯誤會在檢查模型之前就回報。如果請求裡同時有無效的欄位,你會收到 20001,錯誤訊息會指出是哪個欄位,例如 quality。先修正它;如果 ID 仍然錯誤,下一次嘗試時才會出現模型錯誤。

錯誤碼HTTP處理方式
20001400修正錯誤訊息指出的欄位
20002400完全照抄四個模型 ID 之一
10001401檢查 Authorization 標頭

任務也可能在被受理之後才失敗。這時查詢仍然回傳 HTTP 200,但帶有 status: "failed" 和一個 error 物件,例如錯誤碼 60001(內容政策)或 60002(生成失敗)。失敗的任務不收費。錯誤碼目錄列出了每一個錯誤碼,包括餘額與速率限制錯誤,並附上各自的下一步處理方式。

常見問題

有沒有官方 Python SDK 的呼叫方式能直接回傳影像?

在這個 API 上沒有。交付是非同步的:你一定是先提交、保留任務 ID,再輪詢。不支援 stream 和 partial_images。

可以一次要求多張影像嗎?

可以。把 n 設為 1 到 10。完成的任務會為每張交付的影像列出一個 URL,你只為交付的影像付費。

如何取得透明背景的 PNG?

把 background 設為 transparent,output_format 設為 png。JPEG 沒有 alpha 色版,所以這種組合會在執行前就被拒絕。

以任務 ID 為核心完成整合

一拿到任務 ID 就立刻存起來,輪詢時設定期限,並把輪詢逾時視為「仍在執行」而不是「失敗」。其餘所有內容,包括每一個欄位和限制,都在 GPT Image 2.5 API 參考文件裡;你也可以在 Playground 不寫程式碼直接試一次請求。

相關指南