Dokumente

Ein Dokument ist eine einzelne verarbeitete Seite – ein hochgeladenes Bild oder eine aus einem hochgeladenen PDF gerenderte Seite. Jedes Dokument gehört zu einem Batch (identifiziert durch batch_name), der die Einheit ist, die Sie tatsächlich zur Verarbeitung starten. Das Hochladen eines mehrseitigen PDFs erstellt ein Dokument pro Seite im selben Batch – siehe Dokument hochladen unten.

Dokument hochladen

Lädt eine einzelne Datei (Bild, PDF, Word oder Klartext) in einen Batch hoch. Wenn batch_name weggelassen wird, wird einer automatisch generiert und in der Antwort zurückgegeben. Das Hochladen startet keine Extraktion – rufen Sie Batch-Verarbeitung starten auf, sobald Sie alles hochgeladen haben, was zusammen verarbeitet werden soll. Die remaining_batch_capacity der Antwort gibt an, wie viele weitere Dokumente dieser Batch aufnehmen kann, bevor die maximale Batch-Größe Ihres Plans erreicht ist (siehe max_batch_size im Konto) – nützlich, um clientseitig zu entscheiden, ob Sie diesem Batch weitere hinzufügen oder einen neuen starten sollen, ohne eine separate Abfrage.

POST /api/v1/documents

Parameter

Name	Ort	Typ	Beschreibung
`file`	body (multipart)	Datei	Erforderlich, sofern nicht `url` angegeben wird. Ein Bild (JPEG/PNG/etc.), ein PDF, ein Word-Dokument (`.docx` nur — das alte `.doc`-Binärformat wird nicht unterstützt, bitte zuerst als `.docx` speichern) oder eine reine Textdatei (`.txt`). PDFs sind auf 50 Seiten pro Upload begrenzt und werden in ein Dokument pro Seite aufgeteilt; `.docx`/`.txt` werden serverseitig zunächst in PDF konvertiert und dann derselben seitenweisen Aufteilung unterzogen.
`url`	body (multipart)	Zeichenkette, optional	Alternative zu `file` — der Server lädt die Datei von dieser URL herunter, anstatt dass Sie sie anhängen müssen. Schließt sich gegenseitig mit `file` aus; übergeben Sie genau eines. Muss eine öffentliche `http://`- oder `https://`-URL sein (keine Localhost-/Privatnetzwerk-Adressen); der Download ist auf 30 MB mit einem 15-Sekunden-Read-Timeout begrenzt.
`batch_name`	body (multipart)	Zeichenkette, optional	Batch, dem dieses Dokument hinzugefügt werden soll. Auslassen, um automatisch einen neuen Batch-Namen zu generieren (wird in der Antwort zurückgegeben). Denselben Wert bei mehreren Uploads wiederverwenden, um einen Batch aufzubauen, bevor er verarbeitet wird.
`template_id`	body (multipart)	Ganzzahl, optional	Eine Vorlagen-ID, die Ihrem Konto gehört, um sie diesem Dokument vorab zuzuordnen. Nicht erforderlich — Sie können auch eine Vorlage (oder Ad-hoc-Felder) übergeben, wenn Sie `process` aufrufen.
`password`	body (multipart)	Zeichenkette, optional	Nur für PDF. Wird zuerst versucht, wenn die Datei passwortgeschützt ist. Wenn es weggelassen wird oder die Datei nicht entsperrt, wird auf bereits unter den Email-Inbox-Einstellungen Ihres Kontos gespeicherte Passwörter zurückgegriffen — dieses Feld erfordert keine Einrichtung der Email Inbox, es ist lediglich eine aufrufbezogene Alternative dazu.
`Idempotency-Key`	Header, optional	Zeichenkette	Sicher wiederholbar. Siehe Idempotenz.

PDF-Uploads (und konvertierte Word/Text-Uploads) geben ein Array zurück, keine einzelne ID. Beim Hochladen eines PDFs wird jede Seite als eigenes Dokument gerendert, und das document_id der Antwort wird zu einem JSON-Array (eine Zeichenkette pro Seite, in Seitenreihenfolge), plus ein page_count-Feld — ein .docx/.txt-Upload, der in mehr als eine Seite konvertiert wird, verhält sich identisch, da er nach der Konvertierung in PDF-Bytes durch denselben Code-Pfad aufgeteilt wird. Ein einzelner Bild-Upload gibt stattdessen eine skalare Zeichenkette zurück. Client-Code, der annimmt, dass document_id immer eine Zeichenkette ist, wird bei einem mehrseitigen Upload fehlschlagen — prüfen Sie, ob die gesendete Datei mehr als eine Seite erzeugen könnte, und verzweigen Sie basierend auf der Antwortform, oder senden Sie immer Bilder und verlassen Sie sich nie auf den skalaren Fall. Siehe die beiden Antwortbeispiele rechts.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
missing_parameter — es wurde weder file noch url gesendet.
invalid_parameter (param: "file") — ungültiges oder beschädigtes Bild/PDF, ein passwortgeschütztes PDF, das nicht entsperrt werden konnte (weder das password-Feld noch ein gespeichertes Email-Inbox-Passwort funktionierte), ein PDF über der 50-Seiten-Grenze oder eine .docx/.txt-Datei, die nicht konvertiert werden konnte (einschließlich einer alten .doc-Datei — nicht unterstützt, bitte zuerst als .docx speichern).
invalid_parameter (param: "url") — sowohl file als auch url wurden gesendet, die URL löst keine öffentliche Adresse auf, der Download ist fehlgeschlagen oder zeitlich ausgelaufen, oder die heruntergeladene Datei überschreitet 30 MB.
invalid_parameter (param: "batch_name") — der Batch hat bereits die maximale Batch-Größe Ihres Tarifs erreicht.
invalid_parameter (param: "template_id") oder template_not_found.
rate_limit_exceeded — es befinden sich bereits zu viele unverarbeitete (in der Warteschlange befindliche) Dokumente auf dem Konto; verarbeiten oder löschen Sie zuerst einige.

Dokument abrufen

Ruft den aktuellen Status eines einzelnen Dokuments sowie nach erfolgreicher Extraktion dessen umgeformte line_items ab. Dies ist das Einzeldokument-Äquivalent zu Batch-Ergebnisse abrufen — gleiche Umformungsregeln, jedoch ohne die Option ?include=bbox (diese gibt es nur auf dem Batch-Level-Ergebnis-Endpunkt).

GET /api/v1/documents/{document_id}

Parameter

Name	Ort	Typ	Beschreibung
`document_id`	Pfad	Zeichenkette	Die Dokument-ID, die von `POST /documents` zurückgegeben wurde (oder ein Eintrag dieses Arrays für eine PDF-Seite).

status ist immer einer der Werte queued, processing, succeeded, failed, canceled — siehe die Anleitung zum Async-Modell für die Zustandsmaschine. completed_at wird gesetzt, sobald das Dokument einen Endzustand erreicht (succeeded, failed oder canceled) und bleibt davor null.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
document_not_found — kein Dokument mit dieser ID auf Ihrem Konto.

Bild eines Dokuments abrufen

Gibt das Seitenbild eines Dokuments zurück — standardmäßig die gesamte Seite, einen normalisierten Ausschnitt davon mit ?crop= oder eine kleinere, vorgenerierte Vorschau mit ?size=thumb für schnellere Listen-/Rasteransichten. ?crop= versorgt image_url bei reinen Positionsfeldern (siehe Batch-Ergebnisse abrufen), kann aber auch direkt mit eigenen Koordinaten aufgerufen werden.

GET /api/v1/documents/{document_id}/image

Parameter

Name	Ort	Typ	Beschreibung
`document_id`	Pfad	string	Die Dokument-ID.
`crop`	Abfrage, optional	string	`"x1,y1,x2,y2"` — vier Gleitkommazahlen zwischen 0 und 1, dieselbe normalisierte Koordinatenkonvention wie jedes `bbox`-Objekt in der API. Weglassen, um das vollständige, unbeschnittene Seitenbild zu erhalten.
`size`	Abfrage, optional	string	Übergeben Sie `thumb`, um eine kleinere, vorgenerierte Version anstelle der Seite in voller Auflösung zu erhalten. Wird ignoriert, wenn auch `crop` angegeben ist. Fallback auf das vollständige Bild, wenn für dieses Dokument keine Vorschau generiert wurde (kleine Bilder lohnen nicht immer eine Vorschau) — niemals ein Fehler.

Die Antwort sind die rohen Bildbytes (Content-Type: image/jpeg), kein JSON — es gibt rechts für diesen Endpunkt kein JSON-Antwortbeispiel, nur die Anfrage.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
document_not_found — kein Dokument mit dieser ID vorhanden, oder die ursprüngliche Bilddatei ist nicht mehr verfügbar (z. B. weil der automatische Löschzeitraum Ihres Kontos überschritten wurde).
invalid_parameter (param: "crop") — fehlerhafter crop-Wert, Koordinaten außerhalb von 0–1 oder ein Zuschneidebereich, der nach Begrenzung auf die Bildabmessungen leer ist.

Bbox-Annotation auslösen

Startet explizit den optionalen, kostenpflichtigen zweiten Durchlauf, der ermittelt, wo sich jeder extrahierte Feldwert physisch auf der Seite befindet. Dies ist eine separate abrechenbare Aktion von der Extraktion selbst – siehe die Bounding Boxes-Anleitung, bevor Sie dies einbinden, insbesondere den Hinweis zur auto_annotate_bbox-Einstellung Ihres Kontos, die denselben Job möglicherweise automatisch auslöst (und abrechnet), ohne dass Sie diesen Endpunkt jemals aufrufen.

POST /api/v1/documents/{document_id}/bbox

Parameter

Name	Ort	Typ	Beschreibung
`document_id`	Pfad	string	Muss bereits ein `succeeded`-Dokument mit extrahierten Daten sein – Sie können kein Dokument annotieren, dessen Extraktion noch nicht abgeschlossen ist.
`Idempotency-Key`	Header, optional	string	Empfohlen – diese Aktion verbraucht Guthaben. Siehe Idempotenz.

Gibt 202 zurück, wenn ein neuer Bbox-Job gerade in die Warteschlange gestellt wurde, oder 200, wenn für dieses Dokument bereits ein Bbox-Job ausgeführt wird (already_running: true) – d. h. Sie haben diesen Endpunkt bereits einmal für dieses Dokument aufgerufen und dieser frühere Bbox-Job ist noch nicht abgeschlossen. Dies ist unabhängig davon, ob die Extraktion des Dokuments selbst abgeschlossen ist – Bbox kann nur für ein Dokument ausgelöst werden, das bereits succeeded ist (siehe „Mögliche Fehler“ unten). Wenn Sie diesen Endpunkt überhaupt aufrufen können, ist die Extraktion also bereits abgeschlossen. already_running bezieht sich ausschließlich auf einen zweiten Bbox-Job für dasselbe Dokument, nicht auf den Extraktionsjob. In beiden Fällen (202 oder 200) wird auf dem 200-Pfad nichts Neues gestartet oder berechnet – rufen Sie Bbox-Annotation abrufen mit der zurückgegebenen group_batch_id auf, um das Ergebnis zu erhalten.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
document_not_found — kein Dokument mit dieser ID auf Ihrem Konto.
insufficient_credits — nicht genügend Credits für diesen Annotationsdurchlauf.
invalid_parameter — das Dokument befindet sich noch in keinem gültigen Zustand dafür (wird noch verarbeitet) oder enthält keine extrahierten Daten, um Boxen zu lokalisieren.

Bbox-Annotation abrufen

Ruft den Status des letzten für ein Dokument ausgelösten Bbox-Annotationsauftrags ab und holt dessen Ergebnisse. Wenn für dieses Dokument noch nie ein Auftrag ausgelöst wurde, ist exists false und status/group_batch_id sind null — dies ist eine normale, häufige Antwort (die meisten Dokumente haben nie eine Bbox-Annotation), kein Fehler.

GET /api/v1/documents/{document_id}/bbox

Parameter

Name	Ort	Typ	Beschreibung
`document_id`	Pfad	string	Die Dokument-ID.

rows bildet einen Zeilenindex (als String, z. B. "0") auf eine Map von Feldname → normalisiertem bbox-Objekt ab (oder null, wenn die Position dieses Feldes auf der Seite nicht gefunden wurde). status verwendet dasselbe geschlossene 5-Werte-Enum wie überall sonst in der API.

Mögliche Fehler

missing_api_key / invalid_api_key / plan_required — siehe Fehlerbehandlung.
document_not_found — kein Dokument mit dieser ID auf Ihrem Konto.

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, files={"file": open("invoice.jpg", "rb")}, data={"batch_name": "july-invoices"}, ) print(response.json())

import { readFile } from "node:fs/promises"; const formData = new FormData(); formData.append("file", new Blob([await readFile("invoice.jpg")]), "invoice.jpg"); formData.append("batch_name", "july-invoices"); const response = await fetch("https://imagetotable.ai/api/v1/documents", { method: "POST", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Idempotency-Key": crypto.randomUUID(), }, body: formData, }); console.log(await response.json());

curl -X POST https://imagetotable.ai/api/v1/documents \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -F "url=https://imagetotable.ai/static/samples/invoice.webp" \ -F "batch_name=july-invoices"

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, data={ "url": "https://imagetotable.ai/static/samples/invoice.webp", "batch_name": "july-invoices", }, ) print(response.json())

{ "document_id": [ "8f14e45f-ceea-467e-9de1-a3e9c93a9c95_p1", "8f14e45f-ceea-467e-9de1-a3e9c93a9c95_p2" ], "batch_name": "july-invoices", "page_count": 2, "remaining_batch_capacity": 198 }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); console.log(await response.json());

{ "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95", "batch_name": "july-invoices", "filename": "invoice_042.jpg", "status": "succeeded", "created_at": "2026-07-16T09:12:03+00:00", "started_at": "2026-07-16T09:12:05+00:00", "completed_at": "2026-07-16T09:12:14+00:00", "line_items": [ { "invoice_number": "INV-1042", "invoice_date": "2026-07-01", "total_amount": "1,204.50" } ] }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) with open("page.jpg", "wb") as f: f.write(response.content)

import { writeFile } from "node:fs/promises"; const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); await writeFile("page.jpg", Buffer.from(await response.arrayBuffer()));

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, params={"crop": "0.10,0.08,0.42,0.30"}, ) with open("crop.jpg", "wb") as f: f.write(response.content)

import { writeFile } from "node:fs/promises"; const url = new URL("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image"); url.searchParams.set("crop", "0.10,0.08,0.42,0.30"); const response = await fetch(url, { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); await writeFile("crop.jpg", Buffer.from(await response.arrayBuffer()));

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", { method: "POST", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Idempotency-Key": crypto.randomUUID(), }, }); console.log(await response.json());

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); console.log(await response.json());

{ "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95", "exists": true, "status": "succeeded", "group_batch_id": "bx_8a3c2e1f", "rows": { "0": { "invoice_number": {"x1": 0.121, "y1": 0.084, "x2": 0.418, "y2": 0.112, "unit": "normalized"}, "total_amount": null } } }