Lots

Un lot est un groupe nommé d'un ou plusieurs documents que vous traitez, interrogez et dont vous récupérez les résultats ensemble. Vous ne créez pas explicitement un lot — il est créé implicitement la première fois que vous téléchargez un document avec ce batch_name (voir Télécharger un document).

Démarrer le traitement d'un lot

Lance l'extraction sur chaque document éligible actuellement dans le lot (tout document qui n'est pas déjà processing ou succeeded). C'est le point de terminaison qui consomme réellement des crédits — un par document mis en file d'attente.

Paramètres

quality est le seul paramètre du compte que l'API vous permet de remplacer par appel — tous les autres réglages au niveau du compte (bbox auto-annotation, politique de conservation) sont lus depuis votre compte et ne peuvent pas être remplacés par requête. Consultez Paramètres du compte et comportement de l'API pour une vue d'ensemble, y compris pourquoi auto_annotate_bbox peut faire que cet appel vous facture également l'annotation bbox, même si vous n'avez jamais appelé ce point de terminaison.

Le champ webhook_registered de la réponse ne concerne que cet appel spécifique — il est true si et seulement si cette requête incluait webhook_url, et non si le lot a un webhook en général. Un lot dont le webhook a été configuré précédemment via Enregistrer un webhook de lot (et non répété ici) déclenchera correctement son callback à la fin, mais ce champ renvoie toujours false pour cet appel — il ne vérifie pas si un BatchWebhook existe déjà. Ne considérez pas un false ici comme signifiant « aucun webhook ne se déclenchera pour ce lot. »

Appeler à nouveau ce point de terminaison sur un lot que vous avez déjà traité et dont vous avez été notifié — après y avoir téléchargé plus de documents — réarme automatiquement le webhook de ce lot s'il s'était déjà déclenché, afin que la fin de la nouvelle vague vous notifie également. Aucun appel supplémentaire n'est nécessaire pour cela ; consultez la section « Retraiter un lot » du guide des webhooks pour la sémantique exacte (y compris ce qui se passe si deux vagues se chevauchent).

Erreurs possibles

• missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
• batch_not_found — aucun document n'existe sous ce batch_name sur votre compte.
• invalid_parameter — valeur incorrecte de quality/webhook_url/template_id, ou aucun document dans le lot n'est actuellement éligible au traitement (tous déjà terminés/en cours, ou le lot est vide).
• template_not_found
• insufficient_credits — pas assez de crédits disponibles pour couvrir les documents en file d'attente.

Lister les lots

Renvoie une liste paginée et filtrable de vos lots — l'équivalent du « Files Filter » pour les consommateurs de l'API. Cela ne renvoie que des résumés (document_count, status agrégé) ; utilisez Obtenir les résultats d'un lot pour les données complètes par document d'un lot spécifique.

Paramètres

Erreurs possibles

• missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
• invalid_parameter — mode, limit, status ou page_token invalide.

Obtenir le statut d'un lot

Statut agrégé léger pour un lot — comptages par statut public plus un indicateur all_done, utile pour une boucle d'interrogation économique qui n'a pas encore besoin de la charge utile complète des résultats.

Paramètres

Erreurs possibles

• missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
• batch_not_found

Obtenir les résultats d'un lot

Le moyen principal de récupérer les données extraites. Chaque document du lot est renvoyé avec ses line_items remodelés — un tableau d'objets {field_name: value}, un par ligne extraite. Les valeurs au niveau des champs sont des scalaires bruts par défaut (une chaîne, un nombre, etc.).

Paramètres

?include=bbox lit uniquement les résultats déjà calculés — il n'appelle pas Déclencher l'annotation bbox pour vous. Si bbox n'a jamais été déclenché pour un document (manuellement, ou via le paramètre auto_annotate_bbox de votre compte), les champs de ce document sont simplement renvoyés avec "bbox": null.

Les champs de localisation pure sont une troisième forme distincte. Certains champs de modèle demandent au modèle de localiser quelque chose plutôt que de transcrire du texte (par exemple, « localiser la photo du portrait »). Pour ces champs, la valeur entière est une localisation — donc au lieu d'un scalaire ou de la paire {"value","bbox"} ci-dessus, vous obtenez {"type": "image_region", "bbox": {...}, "image_url": "..."}, que ?include=bbox soit défini ou non — la boîte n'est pas une métadonnée optionnelle ici, c'est le seul contenu du champ. image_url pointe vers un JPEG recadré prêt à être récupéré (voir Obtenir l'image d'un document) pour que vous n'ayez pas à recadrer l'original vous-même à partir de quatre nombres.

Chaque objet bbox — quelle que soit sa forme — utilise "unit": "normalized" : les coordonnées sont des flottants de 0 à 1 par rapport à la largeur/hauteur de la page, et non des pixels ou une échelle de 0 à 1000. Consultez le guide Boîtes englobantes pour la mise en garde sur la précision — ces coordonnées proviennent directement du modèle sans vérification au niveau du pixel, considérez-les donc comme « approximatives » plutôt qu'exactes sur des documents denses ou complexes.

Erreurs possibles

• missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
• batch_not_found

Exporter un lot

Un téléchargement pratique — results ci-dessus est le format structuré canonique autour duquel cette API est construite ; ce point de terminaison existe pour extraire les mêmes données dans un tableur sans écrire vous-même de code de remodelage. xlsx uniquement — v1 ne prend en charge que le mode table (extraction), et l'export Word (docx) sur l'application principale est exclusivement la sortie native du mode page_word (une invite et une forme de résultat entièrement différentes), que v1 n'expose pas. Il n'y a pas d'option « données de tableau en tant que document Word » ici.

Paramètres

La réponse est un téléchargement de fichier (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), pas du JSON — il n'y a pas d'exemple de réponse JSON pour ce point de terminaison.

Erreurs possibles

• missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
• batch_not_found
• invalid_parameter (param: "format") — toute valeur autre que xlsx.

Supprimer un lot

Supprime définitivement tous les documents du lot. Tout document encore queued est remboursé avant la suppression. Cela supprime également l'enregistrement du webhook du lot (le cas échéant) et toute tâche d'annotation bbox liée à ses documents.

Paramètres

Erreurs possibles

• missing_api_key / invalid_api_key / plan_required — voir Gestion des erreurs.
• batch_not_found — contrairement à d'autres ressources, la suppression d'un batch_name qui ne vous appartient pas (ou qui n'existe pas) renvoie une erreur 404 ici, et non une opération silencieuse sans effet.