非同期タスク API - WideRouter Docs

非同期タスク API は、2 つのエンドポイントと 1 つのリクエストエンベロープで構成されます。タスクを送信すると、すぐに ID が返され、生成は WideRouter 側で実行されます。モデルの処理中も、リクエスト側で接続を維持する必要はありません。

HTTP 接続を 20–50 秒間開いたままにする必要がある場合は、この API を使用してください。すでに動作する同期インテグレーションがある場合は、移行する前に同期または非同期の選択を参照してください。

エンドポイント

メソッド	パス	目的
`POST`	`/v1/tasks/submit`	タスクを作成します。タスク ID を直ちに返します。
`GET`	`/v1/task/{task_id}`	タスクのステータスを読み取り、完了後は出力も読み取ります。

作成時のパスは複数形で、読み取り時は単数形であることに注意してください。リスト、キャンセル、削除のエンドポイントはありません。

タスクを作成する

リクエストボディは、常に次の3つのキーを持つエンベロープです。 model、input、およびオプションのcallback_urlです。

curl https://api.widerouter.com/v1/tasks/submit \
  -H "Authorization: Bearer $WIDEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "input": {
      "prompt": "a small ceramic teapot on a light-grey studio backdrop",
      "aspect_ratio": "16:9",
      "image_size": "2K"
    }
  }'

import os, requests

resp = requests.post(
    "https://api.widerouter.com/v1/tasks/submit",
    headers={"Authorization": f"Bearer {os.environ['WIDEROUTER_API_KEY']}"},
    json={
        "model": "gemini-3-pro-image",
        "input": {
            "prompt": "a small ceramic teapot on a light-grey studio backdrop",
            "aspect_ratio": "16:9",
            "image_size": "2K",
        },
    },
    timeout=30,
)
task_id = resp.json()["id"]

const resp = await fetch("https://api.widerouter.com/v1/tasks/submit", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WIDEROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gemini-3-pro-image",
    input: {
      prompt: "a small ceramic teapot on a light-grey studio backdrop",
      aspect_ratio: "16:9",
      image_size: "2K",
    },
  }),
});
const { id } = await resp.json();

レスポンスは3つのフィールドで構成され、1秒未満で返されます。

{
  "id": "task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI",
  "status": "queued",
  "created_at": 1788104112
}

エンベロープのフィールド

フィールド	型	必須	備考
`model`	string	はい	サポートされているモデルを参照してください。
`input`	object	はい	JSONオブジェクトである必要があります。文字列または配列は拒否されます。
`callback_url`	string	いいえ	`https` URLである必要があります。コールバックを参照してください。

エンベロープレベルの未知のキーは現在受け付けられ、無視されます。ただし、この動作に依存せず、生成パラメータをそこに配置しないでください。生成パラメータはinputに指定します。

`input`オブジェクト

inputには生成パラメータが含まれ、受け付けるフィールドはモデルによって異なります。その周囲のエンベロープは固定されていますが、内容は固定されていません。 input内のバリデーションは厳格です。モデルが認識しないキーはすべて即座に拒否されるため、タイプミスを見逃さずに検出できます。

{ "error": { "code": "invalid_params", "message": "unknown field", "param": "input.negative_prompt" } }

Nano Banana シリーズ

フィールドの完全な一覧、解像度の段階、アスペクト比、および画像編集。

結果をポーリングする

curl https://api.widerouter.com/v1/task/task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI \
  -H "Authorization: Bearer $WIDEROUTER_API_KEY"

import os, time, requests

def wait(task_id, timeout=600):
    headers = {"Authorization": f"Bearer {os.environ['WIDEROUTER_API_KEY']}"}
    deadline = time.time() + timeout
    while time.time() < deadline:
        task = requests.get(
            f"https://api.widerouter.com/v1/task/{task_id}",
            headers=headers, timeout=30,
        ).json()
        if task["status"] in ("completed", "failed"):
            return task
        time.sleep(3)
    raise TimeoutError(task_id)

完了したタスクは次のようになります。

{
  "id": "task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI",
  "model": "gemini-3-pro-image",
  "status": "completed",
  "created_at": 1788104112,
  "started_at": 1788104113,
  "completed_at": 1788104131,
  "expires_at": 1788190531,
  "outputs": [
    "https://r2cdn.agisuitepro.com/o/2026/08/30/task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI_0.jpg"
  ],
  "counts": { "requested": 1, "succeeded": 1, "failed": 0 }
}

タスクのフィールド

フィールド	存在する場合	備考
`id`	常に	タスク ID です。
`model`	読み取り時は常に	そのまま返されます。作成レスポンスには含まれません。
`status`	常に	`queued`、`in_progress`、`completed`、`failed`です。
`created_at`	常に	Unix 秒、UTC です。
`started_at`	`in_progress`から	ワーカーがタスクを取得した時刻です。
`completed_at`	終端状態	`failed`を含みます。
`expires_at`	`completed`	`created_at`に 24 時間を加えた値です。
`outputs`	`completed`	画像 URL の配列です。リクエストした画像ごとに 1 つ含まれます。
`counts`	終端状態	`requested`、`succeeded`、`failed`です。
`error`	`failed`	`code`と`message`を含むオブジェクトです。

レスポンスはタスクの進行に応じて拡張されます。タスクの実行中は、outputsとexpires_atは単に存在しません。固定された形状を前提にせず、フィールドを防御的に読み取り、まずstatusに基づいて分岐してください。

ステータスの流れ

queued ──► in_progress ──► completed
                       └─► failed

両方の終端状態は最終状態であり、読み取りエンドポイントはべき等です。完了したタスクを繰り返し読み取ると、バイト単位で同一の JSON が返されます。

待機時間

送信処理は 1 秒未満で完了し、負荷がかかってもその状態が維持されます。同時実行数 12 で 30 件のタスクを処理した測定では、p50 は 0.88 秒、p95 は 0.92 秒でした。時間がかかるのは生成処理自体で、モデルと解像度に応じておよそ 12～50 秒です。そのうち 0～11 秒はキュー待ちに費やされます。モデルごとの数値は各モデルのページに記載されています。

2～3 秒ごとにポーリングし、短い間隔でループしないでください。読み取りには単独でも往復に約 0.9 秒かかるため、それより速くポーリングしても何も得られず、レート制限を消費するだけです。

出力のダウンロード

outputsは、署名やクエリ文字列を含まないプレーンなhttpsURLで、APIとは異なるホスト名のWideRouterの配信CDNから提供されます。これにより、次の2点が導かれます。

認証されていません

APIキーを送信してはいけません。また、URL自体を秘密情報として扱ってください。リンクを持っている人は誰でも、そのURLが有効な間は画像を取得できます。

24時間後に期限切れになります

expires_atは常にcreated_atに86400を加えた値です。保持する必要があるものはすべて自分のストレージにコピーしてください。出力URLを永続的な参照として保存してはいけません。

ダウンロード時にはUser-Agentヘッダーを送信してください。 CDNの背後にはWAFがあり、 User-Agentがないリクエストや、デフォルトのPython-urllib/3.xのリクエストに対して、空の403を返します。期限切れのリンクとまったく同じように見えますが、実際には異なります。動作確認済み: ブラウザ、curl、requests、axios、okhttp、Java、Go、 Postman。動作しないもの: ヘッダーのない生のurllib.request.urlopen(url)。

import urllib.request

req = urllib.request.Request(url, headers={"User-Agent": "my-app/1.0"})
with urllib.request.urlopen(req, timeout=120) as r:
    data = r.read()

画像は、C2PAコンテンツ認証情報マニフェストを含むJPEGとして返されます。測定されたファイルサイズは、 1Kで約0.4～0.7 MB、2Kで2.4～3.0 MB、4Kで7.5～8.2 MBです。ファイル拡張子を推測するのではなく、レスポンスからContent-Typeを読み取ってください。

コールバック

作成時に callback_url を設定すると、WideRouter が完了したタスクをそこに POST するため、ポーリングを完全に省略できます。

{
  "model": "gemini-3-pro-image",
  "input": { "prompt": "a paper crane" },
  "callback_url": "https://your-app.example/hooks/widerouter"
}

URL は https でなければなりません。それ以外のもの — http、ホスト名のみの値、文字列以外の値 — は送信時に invalid_callback_url で拒否されるため、誤記があっても、配信されないまま気づけないのではなく、すぐに失敗します。 WideRouter はタスクオブジェクトを application/json として POST します。本文を解析する前にルーティングに使用できるヘッダーも含まれます。

ヘッダー	値
`X-Wide-Event`	`task.completed`
`X-Wide-Task-Id`	タスク ID
`Content-Type`	`application/json`

本文は、その時点で GET /v1/task/{task_id} が返す内容とバイト単位で同一です — フィールドも値も同じであるため、1つのハンドラーで両方の経路に対応できます。テストでは配信は即時に行われました。3つのタスクのコールバックはすべて、タスクが completed に到達してから1秒以内に届きました。エンドポイントが 5xx を返した場合、 WideRouter は再試行します。確認された試行は、およそ0秒、10秒後、70秒後でした。

コールバックには署名がありません。 HMAC ヘッダーはなく、リクエストが WideRouter から送信されたことを証明するのは URL だけです。ペイロードは正式な情報源ではなくヒントとして扱ってください。callback_url には推測しにくい長いパスを使用し、重要な処理を行う前にハンドラーで GET /v1/task/{task_id} を再読み込みしてください。

コールバックはレイテンシーを最適化するものであり、配信を保証するものではありません。コールバックが届かないタスクに備えてポーリングのフォールバックを維持し、ハンドラーは冪等にしてください — 再試行によって同じタスクが複数回届く可能性があるため、タスク id をキーにします。

タスクが失敗した場合

failedタスクは、readエンドポイントでは依然として200です。失敗しているのはHTTPステータスではなく、ボディです。

{
  "id": "task_jodb26qdNoG5CuwzA23OukOgjeH5ktnh",
  "model": "gemini-3-pro-image",
  "status": "failed",
  "created_at": 1788104830,
  "started_at": 1788104831,
  "completed_at": 1788104831,
  "counts": { "requested": 1, "succeeded": 0, "failed": 1 },
  "error": { "code": "input_fetch_error", "message": "fetch input image failed: ..." }
}

outputsもexpires_atもない点に注意してください。入力取得の失敗は、モデル処理の前に発生するため高速で、 1秒未満です。

送信時のエラー

バリデーションは何かがキューに追加される前に行われるため、ここでの400には費用がかかりません。

HTTP	`code`	意味
400	`invalid_params`	不正なフィールドです。`param`がその名前を正確に示します（例：`input.aspect_ratio`）。
400	`invalid_callback_url`	`callback_url`は`https` URLではありません。
400	`model_not_supported`	実在するモデルですが、非同期 API では利用できません。
401	—	`Authorization`ヘッダーがないか、無効です。
404	`task_not_found`	そのタスク IDが存在しないか、お使いのキーに属していません。
503	`model_not_found`	モデル名がプラットフォーム上に存在しません。

エラーは一度に1つのフィールドを指し、paramは配列インデックス（input.images[0]）を含む完全なパスを使用するため、失敗箇所をリクエストに直接対応付けられます。

ここで利用できるモデル

モデル ID は完全一致で照合されます。エイリアスはなく、-previewが付いた名前は受け付けられません。非同期 API で提供されていない ID を送信すると、キューに追加される前の送信時点でmodel_not_supportedが返されます。

Nano Banana シリーズ

Google の画像モデル — 各提供先での利用可否、パラメータ、実測レイテンシ。

同期と非同期の選択

どちらの方式も利用でき、いずれも非推奨ではありません。

	非同期タスク API	同期画像 API
クライアントが接続を保持するか	いいえ、約 0.9 秒	はい、12–50 秒
結果の配信	CDN URL、24 時間	レスポンスボディ内の base64
処理中にクライアントが切断した場合	タスクは完了する	結果は失われ、リクエストの課金は発生する
1 回の呼び出しで複数の画像	`n` 最大 4 枚	利用不可 — `n` は受け付けられて無視され、1 枚の画像が返される
コールバック	はい	いいえ

サーバーレス関数、リバースプロキシ、またはモバイルクライアントの背後で実行する処理では、50 秒のリクエストに確実に耐えられるものはないため、通常は非同期のほうが適しています。単にバイト列を受け取りたいスクリプトでは、同期呼び出しのほうがシンプルです。

次のステップ

Nano Banana シリーズ

パラメータマトリクス、解像度の段階、および2つのモデルの違い。

クイックスタート

エンドツーエンドの同じフローを約5分で実行できます。

​エンドポイント

​タスクを作成する

​エンベロープのフィールド

​inputオブジェクト

Nano Banana シリーズ

​結果をポーリングする

​タスクのフィールド

​ステータスの流れ

​待機時間

​出力のダウンロード

​コールバック

​タスクが失敗した場合

​送信時のエラー

​ここで利用できるモデル

Nano Banana シリーズ

​同期と非同期の選択

​次のステップ

Nano Banana シリーズ

クイックスタート

エンドポイント

タスクを作成する

エンベロープのフィールド

`input`オブジェクト

結果をポーリングする

タスクのフィールド

ステータスの流れ

待機時間

出力のダウンロード

コールバック

タスクが失敗した場合

送信時のエラー

ここで利用できるモデル

同期と非同期の選択

次のステップ