同期と非同期のリクエスト
画像 API の 2 つの呼び出し方。1 回のリクエストで画像を待つか、async true を送ってタスク ID をすぐに受け取り、ポーリングまたは Webhook で結果を取得します。
画像の生成方法は 2 通りあります。どちらも同じパラメータを受け付け、料金も制限も同じです。リクエストごとに選べます。
| 同期(デフォルト) | 非同期 | |
|---|---|---|
| 方法 | リクエストを送って待つ | async: true を付けて、タスク ID をすぐに受け取る |
| 結果が届くタイミング | 20 秒〜数分後、同じレスポンスで | あとで:ポーリングするか、当社が Webhook を呼び出す |
| 接続を保持する時間 | 画像が完成するまで | 1 秒未満 |
| 最長の実行時間 | 7 分 | 10 分 |
| 返るもの | 画像データ(b64_json)またはリンク(url) | リンク(url) |
| 使えるもの | OpenAI SDK と、OpenAI Images API 向けのすべてのツール | 任意の HTTP クライアント |
| 向いている用途 | スクリプト、バックエンド、1 枚ずつの生成 | Web ページ、多数の画像の同時生成、処理の遅いモデル、実行時間の短いサーバーレス関数 |
3 つの呼び出し
| 呼び出し | 内容 |
|---|---|
async: true を付けた POST /v1/images/generations または /v1/images/edits | タスクを開始します。202 とタスク ID を返します |
GET /v1/images/tasks?ids=a,b,c | 最大 100 件のタスクの状態を 1 回のリクエストで取得します |
GET /v1/images/tasks/{id} | 1 件のタスクの状態を取得します |
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": "a red fox in the snow", "async": true}'レスポンスは 202 Accepted で、1 秒もかからずに返ります。
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "in_progress",
"created": 1795062073,
"finished": null,
"model": "gpt-image-2.6"
}id は控えておいてください。知っておくべき点が 3 つあります。
- リンクのみ。 タスクの画像はリンクで返るため、
response_formatは省略するかurlにしてください。b64_jsonは400で拒否されます。 - 不正なリクエストは、あとではなくこの時点で失敗します。 パラメータの誤り(
400)、クレジット不足(402)、リクエスト過多(429)は、同期リクエストと同様に、すぐに返ります。タスクは作成されません。 - ボディにフィールドを追加できない場合は? ヘッダー
Prefer: respond-asyncがasync: trueと同じ働きをします。
2. タスクを取得する
複数のタスクを 1 回のリクエストで取得する
複数のタスクを待っている場合は、すべてをまとめて取得します。10 件のタスクを開始したページでも、ポーリングのリクエストは 10 回ではなく 1 回です。
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 件のタスク ID を指定できます。dataには、指定した順にタスクが入ります。- お客様のアカウントのタスクではない ID や、画像がすでに保存されていない ID は、
not_foundに入ります。リクエスト自体は失敗しません。
1 件のタスク
curl https://api.cheapestimagen.com/v1/images/tasks/req_33ac10d3e9a8e6f120f4c0d3 \
-H "Authorization: Bearer YOUR_KEY"レスポンスは、タスクのオブジェクト 1 件です。存在しない ID には 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 の stable チャンネルでの拒否です。
ポーリングの間隔
2〜5 秒おきで十分です。タスクの取得は無料で、画像リクエストではないため、処理中のリクエスト数には数えられません。タスクは、画像が保存されている 72 時間のあいだ取得できます。
例:Web ページから 10 枚の画像を開始する
開始は画像 1 枚につき 1 回のリクエストで行い、その後は 3 秒おきに、全部をまとめて 1 回のリクエストで確認します。
const API = "https://api.cheapestimagen.com/v1";
const headers = { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" };
// Start 10 tasks.
const prompts = Array.from({ length: 10 }, (_, i) => `a red fox in the snow, variation ${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())
));
// Poll all of them with one request until none is in progress.
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 キーを公開 Web ページに置かないでください。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"a red fox in the snow, variation {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 を使う
webhook_url を追加すると、完了したタスクをそのアドレスに POST します。
{ "model": "gpt-image-2.6", "prompt": "a red fox in the snow", "async": true, "webhook_url": "https://example.com/hooks/images" }- アドレスは、公開ホスト名の
https://である必要があります。 - ボディはタスクのオブジェクトで、
GET /v1/images/tasks/{id}と同じ JSON です。 - 10 秒以内に、任意の
2xxで応答してください。応答がない場合は、3 秒後と 15 秒後にさらに 2 回試行し、その後は停止します。 - 呼び出しに署名を付けるには、ご自身の秘密の値を
webhook_secret(16〜128 文字)としてリクエストに含めます。指定しない場合、呼び出しには署名が付きません。通知として扱い、そこからidを取り出して、内容を信用する前にご自身のキーでタスクを取得してください。 - Webhook が届いたかどうかにかかわらず、タスクは取得できるため、呼び出しを取りこぼしても失うものはありません。
署名を確認する
webhook_secret を指定すると、呼び出しにはヘッダー x-webhook-signature: t=1763560000,v1=5f2b… が付きます。t は呼び出しの時刻(Unix 秒)で、v1 は、テキスト <t>.<body> に対してお客様の秘密の値で計算した HMAC-SHA256 を 16 進数で表したものです。受け取った生のリクエストボディから同じ値を計算して比較し、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 として解析する前の、届いたままの状態で使ってください。秘密の値はこの 1 回のリクエストにのみ使われ、アカウントには保存されません。
制限
非同期リクエストも同期リクエストと同じ数え方で、アカウントごとに 1 分あたり 300 リクエスト、処理中は 50 件までです。50 件が実行中のときに送ったリクエストは 429 で拒否されるため、1 件が終わるのを待ってください。タスクの取得は数えられません。
Idempotency-Key も同じように働きます。そのキーのリクエストが実行中か、成功したあとに再送すると、409 を返します。