同步請求和非同步請求
圖片介面的兩種呼叫方式:一次請求等到出圖,或是加 async true 立刻拿到任務編號,再用一個輪詢請求查一個或多個任務,也可以用回呼通知。
生成圖片有兩種呼叫方式。兩者參數相同、價格相同、限制也是同一套,每次請求都可以自己選。
| 同步(預設) | 非同步 | |
|---|---|---|
| 怎麼用 | 送出請求後等著 | 加 async: true,立刻拿到任務編號 |
| 結果什麼時候來 | 同一個回應裡,等 20 秒到幾分鐘 | 之後:你來輪詢,或者我們回呼通知 |
| 連線佔用多久 | 一直到出圖 | 不到 1 秒 |
| 單次最長執行 | 7 分鐘 | 10 分鐘 |
| 回傳 | 圖片資料(b64_json)或連結(url) | 連結(url) |
| 相容 | OpenAI 官方 SDK,以及所有按 OpenAI 圖片介面寫的工具 | 任何 HTTP 用戶端 |
| 適合 | 腳本、後端服務、一次一張 | 網頁、一次很多張、慢模型、執行時間受限的雲端函式 |
三個介面
| 介面 | 作用 |
|---|---|
POST /v1/images/generations 或 /v1/images/edits,帶 async: true | 建立任務,回傳 202 和任務編號 |
GET /v1/images/tasks?ids=a,b,c | 一次查詢最多 100 個任務的狀態 |
GET /v1/images/tasks/{id} | 查詢單個任務的狀態 |
1. 建立任務
在 POST /v1/images/generations 的請求本文裡加 async: true;POST /v1/images/edits 則作為一個表單欄位。
curl https://api.cheapestimagen.com/v1/images/generations \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-image-2.6", "prompt": "雪地裡的一隻紅狐狸", "async": true}'不到 1 秒就回傳 202 Accepted:
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "in_progress",
"created": 1795062073,
"finished": null,
"model": "gpt-image-2.6"
}把 id 存下來。有三點要知道:
- 只回傳連結。 任務的圖片以連結回傳,所以
response_format不填或填url。填b64_json會回傳400。 - 跑不了的請求當場報錯,不會拖到後面。 參數不對(
400)、積分不夠(402)、請求太多(429),都和同步請求一樣立刻回傳錯誤,不會建立任務。 - 沒辦法加請求本文欄位? 用請求標頭
Prefer: respond-async,效果和async: true相同。
2. 查詢任務
一次查多個任務
同時在等多個任務時,一次全部查完。頁面建立了 10 個任務,就送 1 個輪詢請求,而不是 10 個。
curl "https://api.cheapestimagen.com/v1/images/tasks?ids=req_33ac10d3e9a8e6f120f4c0d3,req_26e50328772b7d62f59d355a" \
-H "Authorization: Bearer YOUR_KEY"{
"object": "list",
"data": [
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "succeeded",
"created": 1795062073,
"finished": 1795062098,
"model": "gpt-image-2.6",
"result": {
"created": 1795062098,
"data": [{ "url": "https://img.cheapestimagen.com/g/req_33ac10d3e9a8e6f120f4c0d3/0.png" }]
}
},
{
"id": "req_26e50328772b7d62f59d355a",
"object": "image.task",
"status": "in_progress",
"created": 1795062074,
"finished": null,
"model": "gpt-image-2.6"
}
],
"not_found": []
}ids最多傳 100 個任務編號,用逗號分隔。data裡的任務順序和你傳的順序一致。- 不屬於你帳號的任務編號,或者圖片已過保存期的任務,會列在
not_found裡,不會讓整個請求失敗。
查單個任務
curl https://api.cheapestimagen.com/v1/images/tasks/req_33ac10d3e9a8e6f120f4c0d3 \
-H "Authorization: Bearer YOUR_KEY"直接回傳這一個任務物件。任務編號不存在時回傳 404。
任務的三種狀態
status | 含義 | 多出來的欄位 |
|---|---|---|
in_progress | 圖片還在生成 | 無 |
succeeded | 已完成 | result:和同步呼叫回傳的內容完全一樣,{ created, data: [{ url }] } |
failed | 沒成功 | error:和同步呼叫回傳的錯誤完全一樣 |
失敗的任務長這樣:
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "failed",
"created": 1795062073,
"finished": 1795062110,
"model": "gpt-image-2.6",
"error": { "message": "The image provider failed. You were not charged.", "type": "api_error", "param": null, "code": "upstream_error" }
}失敗的任務不扣費。唯一的例外和同步請求相同:Nano Banana 穩定通道被內容檢查拒絕。
多久查一次
每 2 到 5 秒查一次就夠了。查詢任務不收費,也不算生圖請求,不佔「進行中的請求」名額。任務可以查 72 小時,也就是圖片的保存期。
範例:網頁一次送出 10 張圖
建立任務時每張圖一個請求,之後每 3 秒用一個請求查全部。
const API = "https://api.cheapestimagen.com/v1";
const headers = { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" };
// 建立 10 個任務
const prompts = Array.from({ length: 10 }, (_, i) => `雪地裡的一隻紅狐狸,第 ${i + 1} 版`);
const started = await Promise.all(prompts.map((prompt) =>
fetch(`${API}/images/generations`, {
method: "POST", headers,
body: JSON.stringify({ model: "gpt-image-2.6", prompt, async: true }),
}).then((r) => r.json())
));
// 用一個請求輪詢全部任務,直到沒有進行中的
let waiting = started.map((t) => t.id);
const done = {};
while (waiting.length) {
await new Promise((r) => setTimeout(r, 3000));
const { data } = await fetch(`${API}/images/tasks?ids=${waiting.join(",")}`, { headers }).then((r) => r.json());
for (const task of data) if (task.status !== "in_progress") done[task.id] = task;
waiting = waiting.filter((id) => !done[id]);
}
for (const task of Object.values(done)) {
console.log(task.status === "succeeded" ? task.result.data[0].url : task.error.message);
}不要把 API 金鑰寫在公開的網頁裡。應該由你自己的伺服器呼叫介面,網頁只和你的伺服器通訊。
範例:Python
import time, requests
API = "https://api.cheapestimagen.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_KEY"}
ids = [
requests.post(f"{API}/images/generations", headers=HEADERS, json={
"model": "gpt-image-2.6", "prompt": f"雪地裡的一隻紅狐狸,第 {i} 版", "async": True,
}).json()["id"]
for i in range(10)
]
done = {}
while len(done) < len(ids):
time.sleep(3)
waiting = [i for i in ids if i not in done]
tasks = requests.get(f"{API}/images/tasks", headers=HEADERS, params={"ids": ",".join(waiting)}).json()["data"]
done.update({t["id"]: t for t in tasks if t["status"] != "in_progress"})
for t in done.values():
print(t["result"]["data"][0]["url"] if t["status"] == "succeeded" else t["error"]["message"])用 OpenAI SDK 時,透過 extra_body={"async": True} 傳這個欄位,查詢任務用一般的 HTTP 請求。
不想輪詢:回呼通知
加上 webhook_url,任務結束時我們會把任務內容 POST 到這個位址:
{ "model": "gpt-image-2.6", "prompt": "雪地裡的一隻紅狐狸", "async": true, "webhook_url": "https://example.com/hooks/images" }- 位址必須是公網網域上的
https://位址。 - 請求本文就是任務物件,和
GET /v1/images/tasks/{id}回傳的 JSON 相同。 - 請在 10 秒內回傳任意
2xx。否則我們會在 3 秒和 15 秒後各再試一次,然後停止。 - 想讓回呼帶簽章,就在請求裡加一個你自己訂的密鑰
webhook_secret(16 到 128 個字元)。不加的話回呼沒有簽章:請把它當作通知,取出裡面的id,用你的金鑰再查一次任務,以查到的內容為準。 - 不管回呼有沒有送達,任務都能照常查詢,所以漏掉一次回呼不會丟結果。
驗證簽章
帶了 webhook_secret 時,回呼請求會有一個請求標頭 x-webhook-signature: t=1763560000,v1=5f2b…。t 是送出回呼的時間(Unix 秒),v1 是用你的密鑰對文字 <t>.<請求本文> 做 HMAC-SHA256 得到的十六進位字串。你用收到的原始請求本文算出同樣的值來比對;t 距離現在超過幾分鐘的請求直接拒絕。
import hashlib, hmac, time
def is_ours(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300import { createHmac, timingSafeEqual } from 'node:crypto';
function isOurs(secret, header, rawBody) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
}請求本文要用收到時的原樣,不要先解析成 JSON 再序列化。這個密鑰只用於這一次請求,不會儲存到你的帳號裡。
限制
非同步請求和同步請求一樣計數:每個帳號每分鐘 300 個請求、同時 50 個進行中。已有 50 個在跑時再送出會回傳 429,等其中一個結束再送出。查詢任務不計數。
Idempotency-Key 的用法不變:帶同一個值的請求還在執行或已經成功時,重複送出會回傳 409。