内容更新日: 2026-09-18

非同期画像生成

画像生成モデルでは、1回の生成に通常20～120秒かかります。同期インターフェースの場合、クライアントはHTTP接続を結果が出るまで維持する必要があり、ゲートウェイ/プロキシの読み取りタイムアウトに遭遇しやすく、返されるbase64データも大きくなります。非同期モードでは、この処理を2回の呼び出しに分けます：

送信：リクエストするとすぐに202とタスクIDが返ります（1秒以内）。
ポーリング：タスクIDを使ってGET /v1/tasks/{id}へ問い合わせ、完了したらresultに画像のhttps URLが入っています（永久にmedia.crazyrouter.comに保存）。base64は返しません。

提交（三种触发方式，见下文）
  POST /v1beta/models/{model}:asyncGenerateContent      # Gemini 系，路径别名
  POST /v1/images/generations  + Prefer: respond-async   # OpenAI 系
  POST /v1/images/edits        + Prefer: respond-async   # OpenAI 系（带参考图）

查询
  GET  /v1/tasks/{task_id}

モデル名、リクエストボディ、課金方式は同期とまったく同じです。 非同期は「いつ結果を取得するか」だけが異なり、同じAPIキーで一部のリクエストを同期、一部を非同期で使うことができます。タスクが失敗した場合は課金されません。

対応モデル

モデル	送信方法	典型的な所要時間
`nano-banana-2`（Gemini 3.1 Flash Image）	`:asyncGenerateContent`	15～30秒
`nano-banana-pro`（Gemini 3 Pro Image）	`:asyncGenerateContent`	30～60秒
`gpt-image-2`、`gpt-image-1.5`、`gpt-image-2.5-*`	`Prefer: respond-async`ヘッダーまたは `async: true`フィールド	60～120秒
その他の画像出力モデル	同様、既存のエンドポイントに従う	—

方法1：Geminiパス別名（Geminiクライアント推奨）

リクエストボディ、ヘッダー、クエリパラメータのどのバイトも変更せずに、動作のサフィックスを:generateContentから:asyncGenerateContentに変更するだけです。

cURL

curl -X POST https://api.crazyrouter.com/v1beta/models/nano-banana-2:asyncGenerateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "draw a cat"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9"}
    }
  }'

返される202：

{
  "id": "task_17754fd677574c3fbfb178ace1ee7551",
  "object": "task",
  "kind": "image",
  "model": "gemini-3.1-flash-image-preview",
  "status": "queued",
  "created_at": 1789716402
}

返されたmodelは解析済みの内部モデル名（例えばgemini-3.1-flash-image-preview）で、課金ログと一致しますが、nano-banana-2で送信することに影響ありません。参考画像編集や同期と同じ方法で、partsにinlineData（base64）またはfileData（URL）を入れるだけです。

:asyncGenerateContentは画像出力モデルのみ受付けます。テキストモデルを使うと400 async mode is only available for image modelsが返ります。ストリーミング動作:streamGenerateContentは非同期に対応していません。

方法2：OpenAI画像エンドポイント＋`Prefer`ヘッダー

既存の/v1/images/generationsまたは/v1/images/editsリクエストにHTTPヘッダーPrefer: respond-asyncを追加するだけです。他は変更不要。リクエストボディフィールド"async": true（JSON）、またはフォームフィールドasync=true（multipart）でも同様に動作します。

curl -X POST https://api.crazyrouter.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a tiny cartoon cat sticker",
    "size": "1024x1024",
    "quality": "low",
    "n": 1
  }'

curl -X POST https://api.crazyrouter.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Prefer: respond-async" \
  -F model=gpt-image-2 \
  -F prompt="turn this into a cartoon cat sticker" \
  -F size=1024x1024 \
  -F quality=low \
  -F image=@reference.png

import requests, time

BASE = "https://api.crazyrouter.com"
H = {"Authorization": "Bearer YOUR_API_KEY"}

r = requests.post(f"{BASE}/v1/images/edits",
                  headers={**H, "Prefer": "respond-async"},
                  data={"model": "gpt-image-2", "prompt": "turn this into a cartoon cat sticker",
                        "size": "1024x1024", "quality": "low"},
                  files={"image": open("reference.png", "rb")})
task_id = r.json()["id"]

while True:
    env = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=H).json()
    if env["status"] in ("completed", "failed"):
        break
    time.sleep(3)

if env["status"] == "completed":
    print(env["result"]["data"][0]["url"])
else:
    print(env["error"])

レスポンスヘッダーにはPreference-Applied: respond-asyncが含まれ、本文は方法1と同様（202＋タスクID）。

タスクの照会

GET https://api.crazyrouter.com/v1/tasks/{task_id}
Authorization: Bearer YOUR_API_KEY

同じアカウントで送信したタスクのみ照会できます。他のアカウントIDはすべて404になります。2～3秒ごとにポーリングし、10分経っても完了しない場合は失敗とみなします。

ステータス

`status`	意味
`queued`	受信済み、実行待ち
`running`	生成中
`completed`	成功、`result`に入力済み
`failed`	失敗、`error`に入力済み、課金なし

完了時のレスポンス（Gemini系）

resultは元のGemini GenerateContentResponseで、inlineDataを画像URL指向のfileDataに変更しただけです：

{
  "id": "task_17754fd677574c3fbfb178ace1ee7551",
  "object": "task",
  "kind": "image",
  "model": "gemini-3.1-flash-image-preview",
  "status": "completed",
  "progress": "100%",
  "created_at": 1789716402,
  "started_at": 1789716403,
  "completed_at": 1789716419,
  "result": {
    "candidates": [{
      "content": {
        "role": "model",
        "parts": [
          {"fileData": {"mimeType": "image/png", "fileUri": "https://media.crazyrouter.com/task-artifacts/2026/09/18/sync-image/task_17754fd677574c3fbfb178ace1ee7551-0.png"}}
        ]
      },
      "finishReason": "STOP"
    }],
    "usageMetadata": {"promptTokenCount": 15, "candidatesTokenCount": 1022, "totalTokenCount": 1037}
  },
  "error": null
}

完了時のレスポンス（OpenAI系）

resultは同期/v1/images/*のレスポンスと同じ形式で、画像はdata[].urlにあります：

{
  "id": "task_b210db17cea14754818e9b965bd8a61c",
  "object": "task",
  "kind": "image",
  "model": "gpt-image-2",
  "status": "completed",
  "result": {
    "created": 1789716295,
    "data": [
      {"url": "https://media.crazyrouter.com/task-artifacts/2026/09/18/sync-image/task_b210db17cea14754818e9b965bd8a61c-0.png"}
    ],
    "usage": {"input_tokens": 77, "output_tokens": 196, "total_tokens": 273}
  },
  "error": null
}

もしbase64が必要な場合は、照会時に?inline=trueを追加すると、サーバー側で保存画像を再読込してinlineData / b64_json（推奨しません、画像が大きいと遅い）を返します。

失敗時のレスポンス

{
  "id": "task_…",
  "status": "failed",
  "result": null,
  "error": {
    "code": "provider_failed",
    "message": "upstream returned 502",
    "retryable": true
  }
}

`error.code`	意味	再試行可
`validation_failed`	リクエストパラメータが拒否された（4xx）	不可
`token_invalid`	APIキーの無効化またはモデル未許可	不可
`insufficient_quota`	残高不足	不可
`rate_limited`	上流/チャネルのレート制限	可
`provider_failed`	上流生成失敗	可
`timeout`	1回の生成が10分を超えた場合	可
`no_image`	モデルが内容を返したが画像がない（例：安全ブロック）。この場合は同期ルール通り通常課金されます。	不可

retryable: trueは新しいタスクを再送信できることを示します。システムは自動再試行しません。

冪等な送信

ネットワーク再試行で同じタスクが重複送信される場合もあります。送信リクエストにIdempotency-Key: <任意の文字列>ヘッダーを付けると、同じアカウントと同じキーで同じタスクIDが返ります（二回目は200が返り、202は返りません）、生成も課金も重複しません。

同期との違い一覧

	同期	非同期
送信レスポンス	生成完了後に画像返却（20～120秒）	1秒以内にタスクID返却
画像形式	URLまたはbase64（チャネルによる）	常にURL
タイムアウトリスク	あり	なし
課金	モデル/サイズによる課金	完全同じ、失敗は課金なし
ルーティング	機能ルーティング	同じ（リプレイでも同じ経路と障害時自動切り替え）
制限	—	各アカウント最大50件未完了タスク、それを超えると`429`を返却

Chat - OpenAI

Chat - Claude

Chat - Gemini

Chat - Responses API

画像生成

動画生成

音声

埋め込み & リランキング

その他の API

リファレンス

非同期画像生成

非同期画像生成

対応モデル

方法1：Geminiパス別名（Geminiクライアント推奨）

方法2：OpenAI画像エンドポイント＋`Prefer`ヘッダー

タスクの照会

ステータス

完了時のレスポンス（Gemini系）

完了時のレスポンス（OpenAI系）

失敗時のレスポンス

冪等な送信

同期との違い一覧

関連ページ

​非同期画像生成

​対応モデル

​方法1：Geminiパス別名（Geminiクライアント推奨）

​方法2：OpenAI画像エンドポイント＋Preferヘッダー

​タスクの照会

​ステータス

​完了時のレスポンス（Gemini系）

​完了時のレスポンス（OpenAI系）

​失敗時のレスポンス

​冪等な送信

​同期との違い一覧

​関連ページ

非同期画像生成

対応モデル

方法1：Geminiパス別名（Geminiクライアント推奨）

方法2：OpenAI画像エンドポイント＋`Prefer`ヘッダー

タスクの照会

ステータス

完了時のレスポンス（Gemini系）

完了時のレスポンス（OpenAI系）

失敗時のレスポンス

冪等な送信

同期との違い一覧

関連ページ