# Bounding Boxes (bbox) – Extrahierte Werte lokalisieren

> bbox ist ein optionaler, separat abgerechneter zweiter Durchlauf, der genau lokalisiert, wo auf der Seite jeder extrahierte Wert herkommt – modellgesteuerte Koordinaten ohne Pixelprüfung, daher ist die Genauigkeit als ungefähr und nicht exakt zu betrachten.

bbox lokalisiert, *wo auf der Originalseite* ein extrahierter Wert herkommt – Koordinaten, mit denen Sie diesen Bereich des Bildes hervorheben oder zuschneiden können.

bbox ist ein **optionaler, separat abgerechneter zweiter Durchlauf**, der nicht automatisch bei jeder Extraktion enthalten ist. Er wird nicht automatisch in einen normalen `process`-Aufruf oder in `results` aufgenommen, es sei denn, Sie fordern ihn explizit an – und, was wichtig ist, er kann auch automatisch durch eine Einstellung auf Kontenebene ausgelöst werden, selbst wenn Sie die bbox-Endpunkte nie selbst aufrufen. Siehe „Abrechnung und Kontoeinstellungen“ unten, bevor Sie annehmen, dass Ihre Nutzung nur dem entspricht, was Sie explizit angefordert haben.

## Annotation auslösen

Sobald ein Dokument die Extraktion abgeschlossen hat (`status: "succeeded"`), lösen Sie den bbox-Durchlauf explizit aus:

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

Dies verbraucht Guthaben und stellt einen bbox-Job in die Warteschlange (202 Accepted) – oder, falls für dieses Dokument bereits ein *bbox*-Job von einem früheren Aufruf desselben Endpunkts läuft, wird 200 zurückgegeben, ohne einen weiteren Job in die Warteschlange zu stellen oder erneut abzurechnen. Dieses `already_running`-Flag bezieht sich auf einen zweiten bbox-Job für dasselbe Dokument, nicht auf die Extraktion des Dokuments – Sie können diesen Endpunkt nur bei einem Dokument erreichen, das bereits `status: "succeeded"` ist, daher ist die Extraktion selbst nie das, was hier „bereits läuft“:

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

Dieser Endpunkt akzeptiert einen `Idempotency-Key`-Header – siehe [Idempotenz](/developers/guides/idempotency), da es sich um eine kostenpflichtige, guthabenverbrauchende Aktion handelt.

## Status und Ergebnisse prüfen

```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` bedeutet, dass für dieses Dokument noch nie ein bbox-Job ausgelöst wurde – ein sehr häufiger, erwarteter Zustand, kein Fehler. Die Koordinaten sind `x1`/`y1`/`x2`/`y2`-Gleitkommazahlen, normalisiert auf den Bereich 0–1 (obere linke und untere rechte Ecke), unabhängig von den tatsächlichen Pixelabmessungen des Originalbilds.

Anstatt diesen Endpunkt abzufragen, registrieren Sie einen Webhook (siehe [Webhook-Leitfaden](/developers/guides/webhooks)) für den Batch des Dokuments – ein bbox-Job, der einen Endstatus erreicht, liefert ein `document.bbox_completed`-Ereignis an dieselbe Callback-URL, zusammen mit allen `batch.completed`-Ereignissen, die er bereits empfängt. Es gibt keinen separaten Registrierungsschritt speziell für bbox; es wird der bestehende Webhook des Batches wiederverwendet.

## bbox inline mit Ergebnissen abrufen

Statt der oben genannten eigenständigen Endpunkte können Sie den Batch-Ergebnis-Endpunkt auch bitten, bereits berechnete bbox-Daten mit `?include=bbox` nachzutragen:

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

Wenn Sie dies tun, ändert jeder Feldwert in `line_items` seine Form von einem einfachen Skalar zu `{"value": ..., "bbox": ...}`, wobei `bbox` auf `null` gesetzt ist, wenn für dieses Feld nichts berechnet wurde:

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

`?include=bbox` liest nur bereits vorhandene Daten aus – es löst niemals einen neuen, kostenpflichtigen Annotation-Job in Ihrem Namen aus. Wenn für ein Feld noch kein bbox berechnet wurde, erhalten Sie dafür `null`, keine implizite Gebühr. Lösen Sie die Annotation explizit zuerst mit `POST .../bbox` aus.

## Felder, die ausschließlich eine Position sind

Manche Felder sind kein Text mit einer beiläufigen Position – der gesamte Zweck des Feldes *ist* die Position (z. B. ein Feld, das auffordert, „das Porträtfoto“ auf einem Ausweisdokument zu lokalisieren). Bei diesen kommt der Wert als ein umfangreicheres Objekt zurück, unabhängig davon, ob Sie `?include=bbox` angefordert haben, da die Position *die* Antwort ist, nicht optionale Metadaten über eine:

```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` verweist auf `GET /documents/{document_id}/image?crop=...` – einen echten, abrufbaren zugeschnittenen JPEG dieses Bereichs (etwas breiter gepolstert als die rohen Koordinaten, damit ein enger Zuschnitt weniger wahrscheinlich einen Teil des Gewünschten abschneidet), nicht nur vier Zahlen, die Sie selbst aus dem Originalbild ausschneiden müssten. Sie können diesen Endpunkt auch direkt mit Ihrem eigenen `?crop=x1,y1,x2,y2` (gleiche normalisierte 0–1-Konvention) für jedes Dokument aufrufen, unabhängig davon, ob es von einem bbox-Job stammt.

## Bekannte Einschränkung: Koordinaten sind modell-direkt, nicht pixelgeprüft

bbox-Koordinaten stammen direkt aus der visuellen Grounding-Fähigkeit des zugrunde liegenden Modells – es gibt **keinen Pixel-Überprüfungsschritt**, der prüft, ob eine bestimmte Box eng oder locker um ihr Ziel gezeichnet ist. Bei einfachen, spärlichen Dokumenten ist dies normalerweise nah genug, um es direkt zu verwenden. Bei komplexen oder dicht gepackten Dokumenten – Tabellen mit vielen Spalten, Formulare mit eng angeordneten Feldern – nimmt die Präzision messbar ab, und Boxen können zu eng, zu locker oder gelegentlich auf das falsche benachbarte Feld verweisen. **Behandeln Sie die bbox-Ausgabe nicht als exakte, pixelgenaue Zuschnittsquelle** – wenn Ihr Workflow von präzisem Zuschnitt abhängt (für nachgelagertes OCR, rechtliche Beweise usw.), überprüfen Sie die Ergebnisse, anstatt ihnen blind zu vertrauen, besonders bei dichten Layouts.

Die praktischen `image_url`-Zuschnitte (sowohl für reine Positionsfelder als auch für Ihre eigenen `?crop=`-Aufrufe gegen eine von bbox abgeleitete Box) werden mit einer kleinen Menge Polsterung um die gemeldeten Koordinaten herum erzeugt, um die Wahrscheinlichkeit zu verringern, dass eine zu enge Box echte Inhalte abschneidet – dies ist eine Nachsichtsmaßnahme, keine Präzisionskorrektur. Die rohen `bbox`-Koordinaten, die im JSON selbst zurückgegeben werden, sind immer genau das, was das Modell gemeldet hat, ungepolstert.

## Abrechnung und Kontoeinstellungen

Ob eine bbox-Annotation ausgeführt wird, hängt nicht zu 100 % davon ab, ob Sie die bbox-Endpunkte selbst aufrufen. Ihr Konto verfügt über eine Einstellung – `auto_annotate_bbox`, die in der Web-App konfiguriert wird, nicht über diese API – die, wenn aktiviert, nach *jeder* abgeschlossenen Extraktion automatisch einen bbox-Durchlauf auslöst (und in Rechnung stellt), auch bei solchen, die über v1 gestartet wurden. Wenn diese Einstellung in Ihrem Konto aktiviert ist, kann Ihnen die bbox-Annotation in Rechnung gestellt werden, ohne dass Sie jemals selbst `POST .../bbox` aufrufen. Weitere Informationen dazu, welche kontospezifischen Einstellungen die API pro Anfrage überschreiben lässt und welche nicht, finden Sie unter [Kontoeinstellungen und API-Verhalten](/developers/guides/account-settings).

---

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