ガイド

バウンディングボックス（bbox）

bboxは、抽出された値が元のページのどこから来たかを特定します。これらの座標を使用して、画像のその領域をハイライト表示したり、クロップしたりできます。

bboxはオプションの別途課金されるセカンドパスであり、すべての抽出に無料で付属するものではありません。通常のprocess呼び出しやresultsに自動的に含まれることはなく、明示的にリクエストする必要があります。また、重要な点として、アカウントレベルの設定によって自動的にトリガーされる場合もあり、自分でbboxエンドポイントを呼び出していなくても課金される可能性があります。ご自身の使用量が明示的にリクエストしたものだけに一致すると想定する前に、以下の「課金とアカウント設定」を参照してください。

アノテーションのトリガー

ドキュメントの抽出が完了したら（status: "succeeded"）、明示的にbboxパスをトリガーします：

curl -X POST https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/bbox \
  -H "Authorization: Bearer $API_KEY"

これによりクレジットが消費され、bboxジョブがキューに入れられます（202 Accepted）。または、このドキュメントに対するbboxジョブが以前の同じエンドポイントへの呼び出しですでに実行中の場合は、キューに入れたり再度課金したりせずに200を返します。このalready_runningフラグは、同じドキュメントに対する2回目のbboxジョブに関するものであり、ドキュメントの抽出に関するものではありません。このエンドポイントにアクセスできるのは、すでにstatus: "succeeded"のドキュメントのみであるため、ここで「すでに実行中」となるのは抽出自体ではありません：

{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "group_batch_id": "bx_8a3c2e1f",
  "status": "processing",
  "already_running": false,
  "row_groups": 1
}

このエンドポイントはIdempotency-Keyヘッダーを受け付けます。詳細はべき等性を参照してください。これは有料でクレジットを消費するアクションです。

ステータスと結果の確認

curl https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/bbox \
  -H "Authorization: Bearer $API_KEY"
{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "exists": true,
  "status": "succeeded",
  "group_batch_id": "bx_8a3c2e1f",
  "rows": {
    "0": {
      "invoice_number": { "x1": 0.121, "y1": 0.084, "x2": 0.312, "y2": 0.108, "unit": "normalized" },
      "total_amount": { "x1": 0.702, "y1": 0.611, "x2": 0.881, "y2": 0.639, "unit": "normalized" }
    }
  }
}

exists: false は、このドキュメントに対して bbox ジョブが一度もトリガーされていないことを意味します。これは非常に一般的で想定内の状態であり、エラーではありません。座標は x1/y1/x2/y2 の浮動小数点数で、0～1の範囲に正規化されており（左上隅と右下隅）、元の画像の実際のピクセルサイズに依存しません。

このエンドポイントをポーリングする代わりに、ドキュメントのバッチにウェブフックを登録してください（ウェブフックガイドを参照）。bbox ジョブが終了ステータスに達すると、同じコールバックURLに document.bbox_completed イベントが配信されます。これは、既に受信している batch.completed イベントに加えて送信されます。bbox 専用の個別の登録手順は不要で、バッチの既存のウェブフックを再利用します。

結果に bbox をインラインで含める

上記のスタンドアロンエンドポイントの代わりに、バッチ結果エンドポイントに ?include=bbox を付けて、既に計算済みの bbox データをバックフィルするようリクエストすることもできます。

curl "https://imagetotable.ai/api/v1/batches/260716-4K9P/results?include=bbox" \
  -H "Authorization: Bearer $API_KEY"

これを行うと、line_items 内のすべてのフィールド値が、単なるスカラー値から {"value": ..., "bbox": ...} という形に変わります。そのフィールドに対して何も計算されていない場合、bbox は null になります。

{ "invoice_number": { "value": "INV-1042", "bbox": { "x1": 0.121, "y1": 0.084, "x2": 0.312, "y2": 0.108, "unit": "normalized" } } }

?include=bbox は既に存在するデータを読み戻すだけで、新たな課金対象のアノテーションジョブをトリガーすることはありません。フィールドの bbox がまだ計算されていない場合は、暗黙の課金は発生せず、null が返されます。アノテーションを明示的にトリガーするには、まず POST .../bbox を使用してください。

純粋な位置情報フィールド

一部のフィールドは、付随的に位置情報を持つテキストではなく、そのフィールドの目的そのものが位置情報です（例：ID書類上の「証明写真の位置を特定する」フィールド）。これらの場合、?include=bboxを指定したかどうかに関わらず、値はよりリッチなオブジェクトとして返されます。なぜなら、位置情報が答えそのものであり、オプションのメタデータではないからです。

{
  "portrait_location": {
    "type": "image_region",
    "bbox": { "x1": 0.05, "y1": 0.12, "x2": 0.28, "y2": 0.44, "unit": "normalized" },
    "image_url": "https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/image?crop=0.03%2C0.10%2C0.30%2C0.46"
  }
}

image_urlはGET /documents/{document_id}/image?crop=...を指しています。これは実際に取得可能な、その領域のクロップ済みJPEGです（生の座標よりも少し広めにパディングされているため、タイトなクロップで目的の一部が欠ける可能性が低くなっています）。単に元画像から自分でクロップしなければならない4つの数値ではありません。また、bboxジョブの結果であるかどうかに関わらず、任意のドキュメントに対して、独自の?crop=x1,y1,x2,y2（同じ0～1の正規化された形式）を指定して、このエンドポイントを直接呼び出すこともできます。

既知の制限：座標はモデル直接出力であり、ピクセル検証済みではない

bbox座標は、基盤となるモデル自身の視覚的根拠から直接得られます。指定されたボックスが対象の周りにタイトに描画されているか、ルーズに描画されているかをチェックするピクセルレベルの検証ステップはありません。シンプルでスパースなドキュメントでは、通常は直接使用できる程度に正確です。複雑または高密度なドキュメント（多数の列を持つテーブル、間隔の狭いフィールドを持つフォーム）では、精度が著しく低下し、ボックスが小さすぎたり、大きすぎたり、時には近くの別のフィールドを参照してしまうことがあります。bbox出力を、正確でピクセルパーフェクトなクロップソースとして扱わないでください。ワークフローが正確なクロッピング（後続のOCR、法的証拠など）に依存している場合は、結果を盲目的に信頼するのではなく、検証してください。特に高密度なレイアウトでは注意が必要です。

image_urlの便利なクロップ（純粋な位置情報フィールドの場合も、bboxから導出されたボックスに対する独自の?crop=呼び出しの場合も）は、報告された座標の周りに少量のパディングを追加して生成されます。これは、タイトすぎるボックスが実際のコンテンツをクリップしてしまう可能性を減らすためのものです。これは許容範囲を広げるための措置であり、精度を修正するものではありません。JSON自体で返される生のbbox座標は、常にモデルが報告した通りの、パディングされていない正確な値です。

請求とアカウント設定

bboxアノテーションが実行されるかどうかは、自分でbboxエンドポイントを呼び出すかどうかだけで100%決まるわけではありません。アカウントにはauto_annotate_bboxという設定があり、これはこのAPIではなくWebアプリ上で設定します。この設定を有効にすると、v1で開始したものを含むすべての完了した抽出の後に、自動的にbboxパスがトリガーされ（課金も発生します）。この設定がオンになっている場合、自分でPOST .../bboxを呼び出さなくても、bboxアノテーションの課金が発生することがあります。リクエストごとにAPIで上書きできるアカウントレベルの設定とできない設定の全体像については、アカウント設定とAPIの動作をご覧ください。

📮 contact email: [email protected]