ガイド

v1 APIにおけるドキュメントとバッチの非同期処理の仕組み — queued/processing/succeeded/failed/canceledのステートマシンと、created_at/started_at/completed_atのタイムスタンプチェーンについて解説します。

ポーリングの代わりにコールバックURLを登録してバッチ完了を通知してもらう方法 — Standard Webhooksの署名検証、イベントペイロードの構造、リトライ動作、bbox完了イベント、バッチの再処理時に自動的に再通知される仕組みについて説明します。

Idempotency-Keyヘッダーを使用すると、ドキュメントのアップロード、バッチ処理、bboxトリガーを安全にリトライでき、同じ操作を二重に実行したり、その料金を支払ったりすることを防げます。

v1 APIのリストエンドポイントは、ページ番号ではなく、不透明なカーソルベースのページネーションを使用します。これは、next_page_token をそのまま渡して使用し、自分でデコードしたり構築したりしないでください。

すべてのv1エラーは、type、code、message、doc_urlを含むJSONオブジェクトとして返されます。このページでは、エラータイプの全分類と個々のエラーコードを網羅しており、返されたdoc_urlのリンク先となります。

v1のレート制限はIPアドレス単位ではなくアカウント単位で適用され、すべてのレスポンスにX-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Resetの各ヘッダーが含まれます。これにより、HTTP 429エラーが発生する前に自己調整が可能です。

bboxはオプションの別途課金されるセカンドパスで、抽出された各値がページ上のどこから来たかを正確に特定します。モデル直接の座標であり、ピクセルレベルの検証は行われないため、精度はおおよそのものとして扱ってください。

v1は、個別のAPI設定レイヤーを公開する代わりに、アカウントのWebアプリ設定（bbox自動アノテート、保持ポリシー、品質）を直接読み取ります。このページでは、APIが常に従う設定と、リクエストごとに上書きできる唯一の設定について正確に説明します。