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 eigentliche Verarbeitungseinheit darstellt. Beim Hochladen eines mehrseitigen PDFs wird ein Dokument pro Seite im selben Batch erstellt – siehe Dokument hochladen unten.

Dokument hochladen

Lädt eine einzelne Datei (Bild oder PDF) 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. Das remaining_batch_capacity-Feld 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 Dokumente hinzufügen oder einen neuen beginnen sollen, ohne eine separate Abfrage durchführen zu müssen.

POST /api/v1/documents

Parameter

Name	Ort	Typ	Beschreibung
`file`	body (multipart)	file	Erforderlich, falls `url` nicht angegeben wird. Ein Bild (JPEG/PNG/etc.) oder ein PDF. PDFs sind auf 30 Seiten pro Upload begrenzt und werden in ein Dokument pro Seite aufgeteilt.
`url`	body (multipart)	string, 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 Lese-Timeout von 15 Sekunden begrenzt.
`batch_name`	body (multipart)	string, optional	Batch, dem dieses Dokument hinzugefügt werden soll. Auslassen, um automatisch einen neuen Batch-Namen zu generieren (wird in der Antwort zurückgegeben). Verwenden Sie denselben Wert bei mehreren Uploads, um einen Batch aufzubauen, bevor Sie ihn verarbeiten.
`template_id`	body (multipart)	integer, optional	Eine Template-ID, die zu Ihrem Konto gehört, um sie diesem Dokument vorab zuzuordnen. Nicht erforderlich – Sie können auch ein Template (oder Ad-hoc-Felder) übergeben, wenn Sie `process` aufrufen.
`password`	body (multipart)	string, 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 eingerichtete Email Inbox, es ist nur eine alternative Angabe pro Aufruf.
`Idempotency-Key`	header, optional	string	Sicher wiederholbar. Siehe Idempotenz.

PDF-Uploads geben ein Array zurück, keine einzelne ID. Beim Hochladen eines PDFs wird jede Seite als eigenes Dokument gerendert und das document_id-Feld der Antwort wird zu einem JSON-Array (ein String pro Seite, in Seitenreihenfolge), plus ein page_count-Feld. Ein einzelner Bild-Upload gibt stattdessen einen skalaren String zurück. Client-Code, der annimmt, dass document_id immer ein String ist, wird bei einem PDF-Upload fehlschlagen – prüfen Sie, ob die gesendete Datei ein PDF ist, 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), oder ein PDF, das die 30-Seiten-Grenze überschreitet.
invalid_parameter (param: "url") — sowohl file als auch url wurden gesendet, die URL löst keine öffentliche Adresse auf, der Download ist fehlgeschlagen oder abgelaufen, 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 (queued) 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-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 (succeeded, failed oder canceled) erreicht, 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.

Dokumentenbild abrufen

Gibt das Seitenbild hinter einem Dokument zurück — standardmäßig die gesamte Seite oder einen normalisierten Ausschnitt davon mit ?crop=. Dies ist die Grundlage für 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	Zeichenkette	Die Dokumenten-ID.
`crop`	Abfrage, optional	Zeichenkette	`"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.

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

Mögliche Fehler

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

Bbox-Annotation auslösen

Startet explizit den optionalen, kostenpflichtigen Zweitdurchlauf, der lokalisiert, wo jeder extrahierte Feldwert physisch auf der Seite sitzt. 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 möglicherweise denselben Job 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 ein Bbox-Job für dieses Dokument bereits läuft (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 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 für das Ergebnis auf.

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 } } }