Batches

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 un lot explicitement — il est créé implicitement lors du premier téléchargement d'un document avec ce batch_name (voir Télécharger un document).

Démarrer le traitement d'un lot

Démarre l'extraction sur chaque document éligible actuellement dans le lot (tout document pas déjà processing ou succeeded). C'est le point de terminaison qui consomme réellement des crédits — 1 crédit par document mis en file si votre compte est sur le Standard niveau de modèle, le niveau par défaut pour tous les comptes. Si votre compte a été assigné Advanced ou Premium à la place, chaque document coûte 3 ou 6 crédits respectivement — le niveau change le modèle qui exécute l'extraction, pas les champs renvoyés ni la forme de la réponse, donc rien d'autre dans le contrat de ce point de terminaison ne change. Il n'y a pas de paramètre tier sur cette requête : le niveau de modèle est un paramètre au niveau du compte que l'équipe ImageToTable.ai assigne, pas quelque chose qu'un appelant choisit par lot. Le niveau en vigueur au moment où ce point de terminaison est appelé est celui qui est facturé, et il reste verrouillé sur les documents qu'il met en file ici même si le niveau du compte change avant leur fin — un lot divisé sur plusieurs appels process peut avoir des documents facturés à différents niveaux si le niveau du compte a changé entre-temps. Voir Paramètres du compte & comportement de l'API pour le tableau complet des paramètres, et Utilisation du compte pour savoir comment une déduction non-Standard est libellée dans votre registre de crédits.

Paramètres

quality est le seul paramètre de compte que l'API vous permet de remplacer par appel — toutes les autres préférences au niveau du compte (auto-annotation bbox, politique de conservation) sont lues depuis votre compte et ne peuvent pas être remplacées par requête. Voir Paramètres du compte et comportement de l'API pour une vue complète, y compris pourquoi auto_annotate_bbox peut signifier que cet appel vous facture aussi l'annotation bbox, même si vous n'avez jamais appelé ce point de terminaison.

Le webhook_registered de la réponse reflète uniquement cet appel spécifique — il est true si et seulement si cette requête incluait webhook_url, pas si le lot a un webhook du tout. 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 revient quand même false pour cet appel — il ne vérifie pas si un BatchWebhook existe déjà. Ne considérez pas un false ici comme « aucun webhook ne se déclenchera pour ce lot ».

Appeler à nouveau ce point de terminaison sur un lot déjà traité et notifié — après avoir téléchargé d'autres documents dedans — réarme automatiquement le webhook de ce lot s'il s'était déjà déclenché, afin que la fin de la nouvelle vague notifie aussi. Aucun appel supplémentaire n'est nécessaire pour que cela se produise ; voir la section « Reprocessing a batch » du guide 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 Error Handling.
• batch_not_found — aucun document n'existe sous ce batch_name sur votre compte.
• invalid_parameter — valeur quality/webhook_url/template_id invalide, ou aucun document du lot n'est actuellement éligible au traitement (tous déjà terminés/en cours de traitement, 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 récapitulative paginée et filtrable de vos lots — l'équivalent « Files Filter » pour les consommateurs de l'API. Cela renvoie uniquement des résumés (document_count, status agrégé) ; utilisez Get batch results pour obtenir 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 — compteurs par statut public plus un indicateur all_done, utile pour une boucle de sondage peu coûteuse qui n'a pas encore besoin de la charge 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 restructuré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 pré-remplis — 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 ex. « localiser la photo de 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 ici une métadonnée facultative, 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) afin 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 nombres flottants de 0 à 1 relatifs à la largeur/hauteur de la page, ni en pixels ni sur une échelle de 0 à 1000. Consultez le guide Bounding Boxes pour la mise en garde sur la précision — ces coordonnées proviennent directement du modèle sans étape de vérification au niveau du pixel, traitez-les donc comme « approximatives » plutôt qu'exactes sur les documents denses ou complexes.

Erreurs possibles

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

Exporter un lot

Un téléchargement pratique — results ci-dessus est le format structuré canonique autour duquel cette API est conçue ; ce point de terminaison existe pour récupérer les mêmes données dans un tableur sans écrire de code de reformatage vous-même. 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 document Word » ici. Une différence de comportement à connaître : si le modèle du lot a fusion multipage configurée, ce point de terminaison l'applique toujours — contrairement à results, il n'y a pas de paramètre de requête de désactivation ici, car un téléchargement de tableur n'a pas de problème de compatibilité avec une intégration existante à préserver.

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 chaque document 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, supprimer 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.