用 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 |
n | 4 | 影像數量,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 不寫程式碼試一條提示詞。



