本文へスキップ
Cheapest Imagen
ガイド

同期と非同期のリクエスト

画像 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"])) < 300
import { 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 を返します。

このページの内容