# バウンディングボックス（bbox）— 抽出値の位置を特定する

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

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

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

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

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

```bash
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"`のドキュメントのみであるため、ここで「すでに実行中」となるのは抽出自体ではありません：

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

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

## ステータスと結果の確認

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

```json
{
  "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の範囲に正規化されており（左上隅と右下隅）、元の画像の実際のピクセルサイズに依存しません。

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

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

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

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

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

```json
{ "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`を指定したかどうかに関わらず、値はよりリッチなオブジェクトとして返されます。なぜなら、位置情報が答えそのものであり、オプションのメタデータではないからです。

```json
{
  "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の動作](/developers/guides/account-settings)をご覧ください。

---

Source: https://imagetotable.ai/ja/developers/guides/bbox