Claude Opus 5.5 已在 SeedRouter 上線

用 Python 呼叫 GPT Image 2 API:完整範例

完整的 GPT Image 2 API Python 範例:提交請求、輪詢任務、把影像下載到本機、用參考圖編輯,並安全地處理錯誤。

以 Markdown 閱讀

要在 Python 中使用 GPT Image 2 API,用 requests 函式庫把請求 POST 到 https://api.seedrouter.ai/v1/images/generations,保存回傳的任務 id,輪詢 /v1/tasks/{id} 直到任務變為 completed,再下載它列出的影像 URL。下面的腳本用大約 40 行完成這四步,並把影像存到本機。

設定好 SEEDROUTER_API_KEY 後即可直接執行。如果你還沒有 Key,請先取得一把。

完整的 GPT Image 2 Python 腳本長什麼樣子?

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}


def submit(body):
    response = requests.post(f"{API}/images/generations", headers=HEADERS, json=body, timeout=60)
    if response.status_code >= 400:
        error = response.json()["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']}")
    return response.json()["id"]


def wait(task_id, limit_seconds=600):
    deadline = time.monotonic() + limit_seconds
    while time.monotonic() < deadline:
        task = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30).json()
        if task["status"] == "completed":
            return [image["url"] for image in task["output"]["data"]]
        if task["status"] == "failed":
            raise RuntimeError(f"{task['error']['code']}: {task['error']['message']}")
        time.sleep(3)
    raise TimeoutError(f"Still running. Resume polling task {task_id}.")


def download(urls, prefix):
    paths = []
    for index, url in enumerate(urls):
        path = f"{prefix}-{index}.png"
        with open(path, "wb") as file:
            file.write(requests.get(url, timeout=60).content)
        paths.append(path)
    return paths


task_id = submit({
    "model": "gpt-image-2",
    "prompt": "A matte ceramic vase on a sunlit table, soft shadows",
    "size": "1024x1024",
    "quality": "low",
    "n": 2,
})
print("task", task_id)
print(download(wait(task_id), "vase"))

用 python example.py 執行。它會先印出任務 ID,然後印出兩個 PNG 檔案的路徑:vase-0.png 和 vase-1.png。

每個函式在做什麼?

submit 傳送請求並回傳任務 ID。錯誤回應一定帶有包含數字 code 和 message 的 error 物件,所以例外訊息會告訴你該修正什麼。例如錯誤碼 20001、message 為 “Check the size parameter against the API documentation.” 的 400,代表尺寸違反了參數指南中的某條規則。

wait 每三秒輪詢一次,直到任務結束。你這一端的期限停下的是迴圈,而不是任務:算繪會繼續進行,之後你可以用同一個 ID 接續輪詢。結果為 failed 的任務會帶著錯誤碼拋出例外,而且不收費。

download 取回任務回傳的每一個 URL 並寫入本機。結果 URL 只是交付時的交接,不是長期儲存空間,所以想保留的請自己存下來。範例在下載和 API 呼叫中都使用 requests;請全程使用同一個 HTTP 用戶端,不要混用標準函式庫的 urllib。

如何修改影像設定?

所有設定都在請求體裡。大多數人最先修改的欄位:

欄位範例作用
size"1536x1024"輸出尺寸;auto 讓模型自行決定
quality"medium"low、medium、high 或 auto
n4影像數量,1 到 10
output_format"jpeg"png 或 jpeg
background"transparent"需要 png

如果修改了 output_format,請把 download 中的 .png 副檔名一併改掉。完整的欄位與限制見 GPT Image 2 API 參考文件。

如何用 Python 編輯影像?

在同一個呼叫裡以 URL 傳入參考圖。沒有獨立的編輯端點;加上 images 就讓請求變成編輯,再加上 mask 就能把修改限制在某一塊區域:

task_id = submit({
    "model": "gpt-image-2",
    "prompt": "Make the vase deep blue. Keep the table and the light unchanged.",
    "images": [{"image_url": "https://example.com/vase.png"}],
})

這些 URL 必須是指向 PNG、JPEG 或 WebP 檔案的公開 HTTPS 連結,最多可傳送 16 張。本機檔案和 base64 字串都會被拒絕,所以請先把影像上傳到你自己的儲存空間,再傳送它的 URL。

提交逾時時,腳本應該怎麼做?

不要馬上再提交一次。POST 逾時並不能證明請求被拒絕;任務可能已經在執行並已扣費。請檢查你最近的任務,或者在確認沒有建立任務之後再重試請求。任務指南說明了如何分辨這兩種情況。

輪詢則不同:輪詢時逾時並無害處,用同一個 ID 再呼叫一次 wait 即可。

常見問題

可以改用 OpenAI Python SDK 嗎?

不能直接使用。這個 API 透過任務 ID 非同步交付結果,而 SDK 的影像呼叫預期回應中就帶有完成的影像。像上面那樣用幾行 requests,就能涵蓋整個流程。

如何執行多條提示詞?

逐一提交每條提示詞,保存所有任務 ID,然後輪詢它們。批次生成指南示範了一個程序重新啟動後也能接續、而且不會重複付費的版本。

gpt-image-2-official 需要不同的程式碼嗎?

不需要。只改 model 字串,其他都不用動。兩個 ID 接受相同的欄位,回傳相同的任務回應;差別只在計費方式。

保存好任務 ID,其餘只是管線工程

提交、保存 ID、設定期限輪詢、下載回傳的結果。這個模式就是整個整合。在寫成腳本之前,可以先在 GPT Image 2 Playground 不寫程式碼試一條提示詞。

相關指南