Batches

Ein Batch ist eine benannte Gruppe aus einem oder mehreren Dokumenten, die Sie gemeinsam verarbeiten, abfragen und Ergebnisse dafür abrufen. Sie erstellen keinen Batch explizit — er wird implizit beim ersten Hochladen eines Dokuments mit diesem batch_name erstellt (siehe Dokument hochladen).

Verarbeitung eines Batches starten

Startet die Extraktion für jedes berechtigte Dokument, das sich derzeit im Batch befindet (alles, was nicht bereits processing oder succeeded ist). Dieser Endpunkt verbraucht tatsächlich Credits — 1 Credit pro Dokument in der Warteschlange, wenn Ihr Konto auf der Standard-Modellstufe ist, der Standardeinstellung, mit der jedes Konto startet. Falls Ihrem Konto stattdessen Advanced oder Premium zugewiesen wurde, kostet jedes Dokument 3 bzw. 6 Credits — die Stufe ändert, welches Modell die Extraktion ausführt, nicht welche Felder zurückkommen oder wie die Antwort strukturiert ist, sodass sich am Vertrag dieses Endpunkts sonst nichts ändert. Es gibt keinen tier-Parameter für diese Anfrage: Die Modellstufe ist eine Kontoeinstellung, die das ImageToTable.ai-Team zuweist, keine Option, die ein Aufrufer pro Batch wählt. Die Stufe, die zum Zeitpunkt des Aufrufs dieses Endpunkts gilt, wird abgerechnet, und sie bleibt für alle Dokumente gesperrt, die hier in die Warteschlange gestellt werden, selbst wenn sich die Kontostufe ändert, bevor sie fertig sind — ein Batch, der über mehrere process-Aufrufe verteilt ist, kann verschiedene Dokumente zu unterschiedlichen Stufen abgerechnet bekommen, wenn sich die Kontostufe dazwischen geändert hat. Siehe Kontoeinstellungen & API-Verhalten für die vollständige Einstellungstabelle und Kontonutzung für die Kennzeichnung einer Nicht-Standard-Abbuchung in Ihrem Credit-Ledger.

Parameter

quality ist die einzige Kontoeinstellung, die die API pro Aufruf überschreiben lässt — jede andere kontoweite Präferenz (bbox-Auto-Annotation, Aufbewahrungsrichtlinie) wird von Ihrem Konto gelesen und kann pro Anfrage nicht überschrieben werden. Siehe Kontoeinstellungen & API- Verhalten für das vollständige Bild, einschließlich warum auto_annotate_bbox dazu führen kann, dass dieser Aufruf Ihnen auch bbox-Annotation in Rechnung stellt, obwohl Sie diesen Endpunkt nie aufgerufen haben.

Das webhook_registered in der Antwort bezieht sich nur auf diesen spezifischen Aufruf — es ist true genau dann, wenn diese Anfrage webhook_url enthielt, nicht ob der Batch überhaupt einen Webhook hat. Ein Batch, dessen Webhook früher über Batch- Webhook registrieren eingerichtet wurde (und hier nicht wiederholt), feuert seinen Callback bei Abschluss korrekt, aber dieses Feld kommt für diesen Aufruf trotzdem als false zurück — es prüft nicht, ob bereits ein BatchWebhook existiert. Behandeln Sie ein false hier nicht als „kein Webhook wird für diesen Batch feuern".

Wenn Sie diesen Endpunkt erneut für einen Batch aufrufen, den Sie bereits verarbeitet haben und über den Sie benachrichtigt wurden — nachdem Sie weitere Dokumente hineingeladen haben — wird der Webhook dieses Batches automatisch wieder scharfgeschaltet, falls er bereits gefeuert hatte, sodass auch der Abschluss der neuen Welle benachrichtigt. Kein zusätzlicher Aufruf ist nötig, um dies zu erreichen; siehe den Abschnitt „Batch erneut verarbeiten" im Webhooks- Leitfaden für die genaue Semantik (einschließlich was passiert, wenn sich zwei Wellen überlappen).

Mögliche Fehler

• missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
• batch_not_found — unter diesem batch_name sind auf Ihrem Konto keine Dokumente vorhanden.
• invalid_parameter — ungültiger quality/webhook_url/template_id-Wert, oder es sind derzeit keine Dokumente im Batch für die Verarbeitung geeignet (alle bereits abgeschlossen/in Verarbeitung, oder der Batch ist leer).
• template_not_found
• insufficient_credits — nicht genügend verfügbare Credits, um die eingereihten Dokumente abzudecken.

Batches auflisten

Gibt eine paginierte, filterbare Übersichtsliste Ihrer Batches zurück — das "Files Filter"-Äquivalent für API-Nutzer. Dies gibt nur Übersichten zurück (document_count, aggregierter status); verwenden Sie Batch-Ergebnisse abrufen für die vollständigen Pro-Dokument-Daten eines bestimmten Batches.

Parameter

Mögliche Fehler

• missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
• invalid_parameter — ungültiger mode, limit, status oder page_token.

Batch-Status abrufen

Leichtgewichtiger aggregierter Status für einen Batch — Zählungen pro öffentlichem Status plus ein all_done-Flag, nützlich für eine kostengünstige Polling-Schleife, die die vollständige Ergebnis-Payload noch nicht benötigt.

Parameter

Mögliche Fehler

• missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
• batch_not_found

Batch-Ergebnisse abrufen

Der primäre Weg, extrahierte Daten abzurufen. Jedes Dokument im Batch wird mit seinen umgeformten line_items zurückgegeben — ein Array von {field_name: value}-Objekten, eines pro extrahierter Zeile. Feldwerte sind standardmäßig einfache Skalare (ein String, eine Zahl usw.).

Parameter

?include=bbox liest nur nachträglich gefüllte Ergebnisse — es ruft bbox-Annotation auslösen nicht für Sie auf. Wenn bbox für ein Dokument nie ausgelöst wurde (manuell oder über die auto_annotate_bbox-Einstellung Ihres Kontos), werden die Felder dieses Dokuments einfach mit "bbox": null zurückgegeben.

Reine Positionsfelder sind eine dritte, eigene Form. Einige Vorlagenfelder bitten das Modell, etwas zu lokalisieren statt Text zu transkribieren (z. B. „das Porträtfoto lokalisieren"). Bei solchen Feldern ist der gesamte Wert eine Position — Sie erhalten also statt eines Skalars oder des {"value","bbox"}-Paars oben {"type": "image_region", "bbox": {...}, "image_url": "..."}, unabhängig davon, ob ?include=bbox gesetzt ist — die Box ist hier keine optionale Metadaten, sondern der einzige Inhalt des Felds. image_url verweist auf ein abrufbares zugeschnittenes JPEG (siehe Dokumentbild abrufen), sodass Sie das Original nicht selbst aus vier Zahlen zuschneiden müssen.

Jedes bbox-Objekt — in beiden Formen — verwendet "unit": "normalized": Die Koordinaten sind Gleitkommazahlen von 0 bis 1 relativ zur Breite/Höhe der Seite, nicht Pixel und keine 0–1000-Skala. Siehe den Bounding Boxes-Leitfaden für den Hinweis zur Genauigkeit — diese Koordinaten stammen direkt vom Modell ohne Pixel-Level-Verifizierung, behandeln Sie sie also bei dichten oder komplexen Dokumenten als „ungefähr" statt exakt.

Mögliche Fehler

• missing_api_key / invalid_api_key / plan_required — siehe Error Handling.
• batch_not_found

Batch exportieren

Ein praktischer Download — results oben ist das kanonische, strukturierte Format, um das diese API aufgebaut ist; dieser Endpunkt dient dazu, dieselben Daten ohne eigenes Umformungs-Skript in eine Tabellenkalkulation zu bringen. Nur xlsx — v1 unterstützt nur den Tabellenmodus (Extrahieren), und der Word-Export (docx) in der Haupt-App ist ausschließlich die native Ausgabe des page_word-Modus (ein völlig anderer Prompt und eine andere Ergebnisstruktur), die v1 nicht bereitstellt. Es gibt hier keine Option „Tabellendaten als Word-Dokument". Ein Verhaltensunterschied, den Sie kennen sollten: Wenn die Vorlage des Batches Mehrseiten-Zusammenführung konfiguriert hat, wendet dieser Endpunkt sie immer an — anders als results gibt es hier keinen Opt-out-Abfrageparameter, da ein Tabellenkalkulations-Download keine Kompatibilitätsbedenken mit bestehenden Integrationen zu wahren hat.

Parameter

Die Antwort ist ein Datei-Download (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), kein JSON — für diesen Endpunkt gibt es kein JSON-Antwortbeispiel.

Mögliche Fehler

• missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
• batch_not_found
• invalid_parameter (param: "format") — alles außer xlsx.

Batch löschen

Löscht dauerhaft jedes Dokument im Batch. Jedes Dokument, das noch queued ist, wird vor dem Löschen erstattet. Dies entfernt auch die Webhook-Registrierung des Batches (falls vorhanden) sowie alle bbox-Annotationsaufträge, die mit seinen Dokumenten verknüpft sind.

Parameter

Mögliche Fehler

• missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
• batch_not_found — anders als bei einigen anderen Ressourcen ist das Löschen eines batch_name, der Ihnen nicht gehört (oder der nicht existiert), hier ein 404 und kein stiller No-op.