Bounding Boxes (bbox)

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:

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“:

{
  "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, da es sich um eine kostenpflichtige, guthabenverbrauchende Aktion handelt.

Status und Ergebnisse prüfen

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 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) 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:

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:

{ "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:

{
  "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.