# 경계 상자(bbox) — 추출된 값의 위치 찾기

> bbox는 선택 사항이며 별도로 청구되는 두 번째 패스로, 각 추출 값이 페이지의 어디에서 왔는지 정확히 찾아냅니다. 모델이 직접 제공하는 좌표이며 픽셀 수준의 검증은 없으므로 정밀도는 근사치로 간주하세요.

bbox는 추출된 값이 *원본 페이지의 어디에서* 왔는지 찾아냅니다. — 해당 이미지 영역을 강조 표시하거나 자르는 데 사용할 수 있는 좌표입니다.

bbox는 모든 추출에 무료로 제공되는 기능이 아니라 **선택 사항이며 별도로 청구되는 두 번째 패스**입니다. 일반적인 `process` 호출이나 `results`에 자동으로 포함되지 않으며, 명시적으로 요청해야 합니다. 또한 계정 수준 설정에 의해 자동으로 트리거될 수 있으므로, 사용량이 직접 요청한 것과만 일치한다고 가정하기 전에 아래 "청구 및 계정 설정"을 먼저 확인하세요.

## 주석 트리거

문서 추출이 완료되면(`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` 플래그는 동일한 문서에 대한 두 번째 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` float 값으로, 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가 없으면 `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`를 사용하세요.

## 위치 자체가 전부인 필드

일부 필드는 텍스트 조각에 위치가 부수적으로 붙어 있는 것이 아니라, 필드의 존재 목적 자체가 *위치*입니다. 이러한 필드의 경우, `?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입니다. 단순히 원본 이미지에서 직접 잘라내야 하는 네 개의 숫자가 아닙니다. 또한 bbox 작업에서 나온 문서가 아니더라도 모든 문서에 대해 `?crop=x1,y1,x2,y2`를 사용하여 해당 엔드포인트를 직접 호출할 수 있습니다.

## 알려진 한계: 좌표는 모델 직접 출력이며, 픽셀 검증되지 않음

bbox 좌표는 기본 모델의 자체 시각적 근거(visual grounding)에서 직접 가져옵니다. 주어진 박스가 대상 주위에 빡빡하게 또는 느슨하게 그려졌는지 확인하는 **픽셀 수준의 검증 단계는 없습니다**. 단순하고 항목이 적은 문서에서는 일반적으로 직접 사용하기에 충분히 정확합니다. 그러나 열이 많은 테이블, 필드가 빽빽하게 배치된 양식과 같은 복잡하거나 밀집된 문서에서는 정밀도가 눈에 띄게 저하되며, 박스가 너무 빡빡하거나 너무 느슨해지거나, 드물게는 근처의 다른 필드를 참조할 수 있습니다. **bbox 출력을 정확하고 픽셀 단위까지 완벽한 크롭 소스로 취급하지 마십시오**. 워크플로우가 정밀한 크롭에 의존하는 경우, 특히 밀집된 레이아웃에서는 결과를 맹목적으로 신뢰하지 말고 검증하십시오.

`image_url` 편의 크롭은 보고된 좌표 주위에 소량의 패딩을 추가하여 생성됩니다. 이는 너무 빡빡한 박스가 실제 콘텐츠를 잘라낼 가능성을 줄이기 위한 것입니다. 이는 관용 조치이지 정밀도 수정이 아닙니다. JSON 자체에서 반환되는 원시 `bbox` 좌표는 항상 모델이 보고한 그대로이며 패딩되지 않습니다.

## 결제 및 계정 설정

bbox 주석 실행 여부는 사용자가 직접 bbox 엔드포인트를 호출하는지에 따라 100% 결정되지 않습니다. 계정에는 `auto_annotate_bbox`라는 설정이 있습니다. 이 설정은 웹 앱에서 구성되며, 이 API를 통해 구성되지 않습니다. 이 설정이 활성화되면 v1을 통해 시작된 추출을 포함하여 *모든* 완료된 추출 후에 bbox 패스가 자동으로 트리거되고. 계정에 이 설정이 켜져 있으면 사용자가 직접 `POST .../bbox`를 호출하지 않아도 bbox 주석에 대한 요금이 청구될 수 있습니다. API가 요청별로 재정의할 수 있는 계정 수준 설정과 그렇지 않은 설정에 대한 전체 내용은 [계정 설정 및 API 동작](/developers/guides/account-settings)을 참조하세요.

---

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