Documents

Un Document est une page unique traitée — une image téléchargée, ou une page extraite d'un PDF téléchargé. Chaque Document appartient à un Batch (identifié par batch_name), qui est l'unité sur laquelle vous lancez réellement le traitement. Le téléchargement d'un PDF multipage crée un Document par page dans le même batch — voir Télécharger un document ci-dessous.

Télécharger un document

Télécharge un fichier unique (image ou PDF) dans un batch. Si batch_name est omis, un nom est généré automatiquement et renvoyé dans la réponse. Le téléchargement ne démarre pas l'extraction — appelez Démarrer le traitement d'un batch une fois que vous avez téléchargé tout ce que vous souhaitez traiter ensemble. Le champ remaining_batch_capacity de la réponse vous indique combien de documents supplémentaires ce batch peut accepter avant d'atteindre la taille maximale de votre plan (voir max_batch_size du Compte) — utile pour décider côté client s'il faut continuer à ajouter des documents à ce batch ou en créer un nouveau, sans requête séparée.

POST /api/v1/documents

Paramètres

Nom	Emplacement	Type	Description
`file`	body (multipart)	fichier	Obligatoire si `url` n'est pas fourni. Une image (JPEG/PNG/etc.) ou un PDF. Les PDF sont limités à 30 pages par téléversement et sont découpés en un Document par page.
`url`	body (multipart)	chaîne, optionnel	Alternative à `file` — le serveur télécharge le fichier depuis cette URL au lieu de devoir l'attacher. Mutuellement exclusif avec `file` ; ne passer qu'un seul des deux. Doit être une URL publique `http://` ou `https://` (pas d'adresse locale/réseau privé) ; le téléchargement est limité à 30 Mo avec un délai d'attente de 15 secondes.
`batch_name`	body (multipart)	chaîne, optionnel	Batch auquel ajouter ce Document. Omettre pour générer automatiquement un nouveau nom de batch (renvoyé dans la réponse). Réutiliser la même valeur pour plusieurs téléversements afin de constituer un batch avant de le traiter.
`template_id`	body (multipart)	entier, optionnel	Un ID de Template appartenant à votre compte, à pré-associer à ce Document. Non obligatoire — vous pouvez aussi passer un template (ou des champs ad hoc) lors de l'appel à `process`.
`password`	body (multipart)	chaîne, optionnel	PDF uniquement. Tenté en premier si le fichier est protégé par mot de passe. S'il est omis ou ne déverrouille pas le fichier, on utilise les mots de passe déjà enregistrés dans les paramètres Email Inbox de votre compte — ce champ ne nécessite pas d'avoir configuré Email Inbox, c'est simplement une alternative par appel.
`Idempotency-Key`	en-tête, optionnel	chaîne	Réessai sans risque. Voir Idempotence.

Les téléversements PDF renvoient un tableau, pas un ID unique. Téléverser un PDF transforme chaque page en son propre Document et le champ document_id de la réponse devient un tableau JSON (une chaîne par page, dans l'ordre des pages), plus un champ page_count. Un téléversement d'image unique renvoie une chaîne scalaire. Un code client qui suppose que document_id est toujours une chaîne échouera avec un PDF — vérifiez si le fichier envoyé est un PDF et adaptez-vous à la forme de la réponse, ou envoyez toujours des images sans jamais compter sur le cas scalaire. Voir les deux exemples de réponse à droite.

Erreurs possibles

missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
missing_parameter — ni file ni url n'ont été envoyés.
invalid_parameter (param: "file") — image ou PDF invalide/corrompu, PDF protégé par mot de passe qui n'a pas pu être déverrouillé (ni le champ password ni aucun mot de passe Email Inbox enregistré n'a fonctionné), ou PDF dépassant la limite de 30 pages.
invalid_parameter (param: "url") — file et url ont été envoyés ensemble, l'URL ne pointe pas vers une adresse publique, le téléchargement a échoué ou expiré, ou le fichier téléchargé dépasse 30 Mo.
invalid_parameter (param: "batch_name") — le batch a déjà atteint la taille maximale autorisée par votre formule.
invalid_parameter (param: "template_id") ou template_not_found.
rate_limit_exceeded — trop de documents non traités (en file d'attente) sur le compte ; traitez-en ou supprimez-en d'abord.

Récupérer un document

Récupère le statut actuel d'un seul document et, une fois l'extraction réussie, ses line_items remodelés. C'est l'équivalent pour un seul document de Récupérer les résultats d'un batch — mêmes règles de remodelage, mais sans l'option ?include=bbox (disponible uniquement sur le point de terminaison des résultats au niveau du batch).

GET /api/v1/documents/{document_id}

Paramètres

Nom	Emplacement	Type	Description
`document_id`	chemin	chaîne	L'identifiant du document renvoyé par `POST /documents` (ou une entrée de ce tableau, pour une page PDF).

status est toujours l'une des valeurs suivantes : queued, processing, succeeded, failed, canceled — voir le guide Modèle asynchrone pour la machine à états. completed_at est défini une fois que le document atteint un état terminal (succeeded, failed ou canceled) et reste null avant cela.

Erreurs possibles

missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
document_not_found — aucun document avec cet identifiant sur votre compte.

Obtenir l'image d'un document

Renvoie l'image de la page d'un document — la page entière par défaut, ou un recadrage normalisé avec ?crop=. C'est ce qui alimente image_url sur les champs de localisation pure (voir Obtenir les résultats d'un batch), mais vous pouvez aussi l'appeler directement avec vos propres coordonnées.

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

Paramètres

Nom	Emplacement	Type	Description
`document_id`	chemin	chaîne	L'identifiant du document.
`crop`	requête, optionnel	chaîne	`"x1,y1,x2,y2"` — quatre nombres flottants entre 0 et 1, suivant la même convention de coordonnées normalisées que tout objet `bbox` ailleurs dans l'API. Omettez pour obtenir l'image de la page entière, non recadrée.

La réponse est constituée des octets bruts de l'image (Content-Type: image/jpeg), pas du JSON — il n'y a pas d'exemple de réponse JSON à droite pour ce point de terminaison, seulement la requête.

Erreurs possibles

missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
document_not_found — aucun document avec cet identifiant, ou le fichier image d'origine n'est plus disponible (par exemple, il dépasse la fenêtre de conservation avec suppression automatique de votre compte).
invalid_parameter (param: "crop") — valeur crop mal formée, coordonnées en dehors de 0–1, ou région de recadrage vide après ajustement aux limites de l'image.

Déclencher l'annotation bbox

Lance explicitement la tâche optionnelle payante de second passage qui localise l'emplacement physique de chaque valeur de champ extraite sur la page. Il s'agit d'une action facturable distincte de l'extraction elle-même — consultez le guide Bounding Boxes avant d'intégrer cette fonctionnalité, en particulier la note concernant le paramètre auto_annotate_bbox de votre compte qui pourrait déclencher (et facturer) automatiquement cette même tâche sans que vous n'ayez jamais à appeler ce point d'accès.

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

Paramètres

Nom	Emplacement	Type	Description
`document_id`	chemin	string	Doit déjà être un document `succeeded` avec des données extraites — vous ne pouvez pas annoter un document dont l'extraction n'est pas terminée.
`Idempotency-Key`	en-tête, optionnel	string	Recommandé — cette action consomme des crédits. Voir Idempotence.

Renvoie 202 lorsqu'une nouvelle tâche bbox vient d'être mise en file d'attente, ou 200 lorsqu'une tâche bbox pour ce document était déjà en cours d'exécution (already_running: true) — ce qui signifie que vous avez déjà appelé ce même point d'accès pour ce document auparavant et que cette tâche bbox antérieure n'est pas encore terminée. Ceci est indépendant du fait que l'extraction du document soit terminée ou non — bbox ne peut être déclenché que sur un document déjà succeeded (voir « Erreurs possibles » ci-dessous), donc au moment où vous pouvez appeler ce point d'accès, l'extraction est déjà terminée. already_running concerne uniquement une seconde tâche bbox pour le même document, et non la tâche d'extraction. Dans les deux cas (202 ou 200), rien de nouveau n'est démarré ou facturé sur le chemin 200 — interrogez Obtenir l'annotation bbox avec le group_batch_id renvoyé pour obtenir le résultat.

Erreurs possibles

missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
document_not_found — aucun Document avec cet identifiant sur votre compte.
insufficient_credits — crédits insuffisants pour exécuter cette passe d'annotation.
invalid_parameter — le Document n'est pas dans un état valide pour cette opération (toujours en cours de traitement), ou ne contient pas de données extraites pour localiser les boîtes.

Obtenir l'annotation bbox

Interroge le statut et récupère les résultats du dernier job d'annotation bbox déclenché pour un Document. Si aucun job n'a jamais été déclenché pour ce Document, exists est false et status/group_batch_id sont null — il s'agit d'une réponse normale et courante (la plupart des Documents n'ont jamais de bbox déclenché), et non d'une erreur.

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

Paramètres

Nom	Emplacement	Type	Description
`document_id`	path	string	L'identifiant du Document.

rows associe un index de ligne (sous forme de chaîne, ex. "0") à une correspondance de nom de champ → objet bbox normalisé (ou null si l'emplacement de ce champ n'a pas été trouvé sur la page). status utilise la même énumération fermée à 5 valeurs qu'ailleurs dans l'API.

Erreurs possibles

missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
document_not_found — aucun Document avec cet identifiant sur votre compte.

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