3つのエンドポイントの比較
どれを使うか
- 500タスクまでで、再試行を自分で扱う場合:
POST /v1/async/task/batch。レスポンスですべてのタスクidを受け取れます。 - プランの同時実行数を超えるタスク、または数千件の日次ジョブ:
POST /v1/batches。サーバーが項目を保持し、プランの上限と各エンジンのキューが許す分だけ投入するため、429や503を自分で再試行する必要はありません。 - 1つのプロンプトを、ある場所の周辺の多数の地点から問い合わせる場合:
POST /v1/async/task/grid。
POST /v1/async/task/batch
最大500件のタスクリクエストの配列を送信します(リファレンス)。エンジンは混在できます。
200 を返します。results[i].index は配列内の位置に対応し、各結果は task または error のどちらかを持ちます。
idempotencyKey が重複した場合は、既存のタスクを成功として返します。冪等性を参照してください。
POST /v1/batches
最大10,000件の項目を送信します(リファレンス)。各項目はタスクのフィールド taskType、payload、priority、idempotencyKey に加え、結果にそのまま返る任意の customId(最大128文字)を受け付けます。webhook.url は項目ではなくバッチに指定してください。
202 でバッチを返します。最初の項目は既に送信されています。
エンベロープのルール
すべてか無しかの検証
何かを保存する前に、すべての項目に単発タスクと同じ検査(フィールド、キーの範囲、非公開エンジン、専用エンドポイント、地域、payload.location)を行います。1件でも失敗すると、レスポンスは 400 VALIDATION_ERROR で何も保存されず、details に失敗した項目を最大50件示します。
項目の実行
バッチは、プランの上限とエンジンのキューに空きがあるときに項目をタスクとして投入します。アカウントは順番に処理されるため、大きなバッチが他のアカウントの小さなバッチを妨げることはありません。投入された項目は単発タスクと同じ受け付け処理を通り、クレジットを確保し、キーの1日のクレジット上限にも計上されます。 項目が拒否されたときの扱いはコードで決まります。
保留中の項目がなくなり、すべてのタスクが終了すると、バッチは
COMPLETED になります。webhook.url がある場合、サーバーはその後 batch.completed イベントをPOSTします。
進捗と結果を読み取る
GET /v1/batches/{id} は、項目のステータス(pending、queued、processing、completed、failed、rejected)ごとの counts を含むバッチを返します。これをポーリングすると、保留中の項目の投入も進みます。
GET /v1/batches/{id}/items は項目を送信順に一覧します。
REJECTED の項目は error: { code, message } を持ちます。結果本文が含まれるのは、非同期タスクの24時間のポーリング期間内だけです。バッチを取得とバッチ項目を一覧も参照してください。
POST /v1/async/task/grid
中心の周囲にある正方形グリッドのすべての地点から、1つのプロンプトを問い合わせます(リファレンス)。各地点はその地点を payload.location とするタスクになるため、エンジンは位置を受け付けるもの(CHATGPT、GEMINI、GOOGLE、AIMODE、GOOGLE_SERP)である必要があります。payload.location は自分で指定しないでください。
行0が北端、列0が西端です。レスポンスは
grid(id と spacingMeters を含む)、summary、行順の points を返し、各地点は row、col、location と、task または error のどちらかを持ちます。
中心点が最初に単独で受け付けられます。中心点が拒否された場合(たとえば 422 LOCATION_UNSUPPORTED、403 KEY_SCOPE_DENIED、402 INSUFFICIENT_CREDITS、またはプランの上限に達している場合)、そのエラーがグリッド全体のレスポンスとなり、タスクは作成されません。中心点より後に容量の理由で拒否された地点は、success: false としてその場で失敗します。
グリッドは GET /v1/async/task/grid/{id} で読み取れます。?include=response を付けると、終了したタスクの結果が加わります。受け付けられなかった地点は含まれず、他のアカウントのグリッドidは 404 を返します。同じグリッドを同じidで再送信すると、欠けている地点だけが受け付けられます。冪等性を参照してください。
次のステップ
冪等性
各エンドポイントが重複したキーをどう扱うか。
クレジットと上限
プランの同時実行数とペース配分。