Zones de délimitation (bbox)

bbox localise sur la page d'origine d'où provient une valeur extraite — des coordonnées que vous pouvez utiliser pour surligner ou recadrer cette région de l'image.

bbox est une seconde passe optionnelle et facturée séparément, pas quelque chose d'inclus gratuitement avec chaque extraction. Elle n'est pas automatiquement incluse dans un appel process normal ni dans results sauf si vous la demandez explicitement — et, surtout, elle peut aussi être déclenchée automatiquement par un paramètre au niveau du compte même si vous n'appelez jamais vous-même les endpoints bbox. Voir « Facturation et paramètres du compte » ci-dessous avant de supposer que votre utilisation correspond uniquement à ce que vous avez explicitement demandé.

Déclencher l'annotation

Une fois qu'un document a fini l'extraction (status: "succeeded"), déclenchez la passe bbox explicitement :

curl -X POST https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/bbox \
  -H "Authorization: Bearer $API_KEY"

Cela consomme des crédits et met en file d'attente un job bbox (202 Accepted) — ou, si un job bbox pour ce document est déjà en cours suite à un appel antérieur au même endpoint, renvoie 200 sans remettre en file d'attente ni facturer à nouveau. Ce flag already_running concerne un second job bbox pour le même document, pas l'extraction du document — vous ne pouvez atteindre cet endpoint que sur un document déjà en status: "succeeded", donc l'extraction elle-même n'est jamais ce qui est « déjà en cours » ici :

{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "group_batch_id": "bx_8a3c2e1f",
  "status": "processing",
  "already_running": false,
  "row_groups": 1
}

Cet endpoint accepte un en-tête Idempotency-Key — voir Idempotence, car il s'agit d'une action payante consommant des crédits.

Vérification du statut et des résultats

curl https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/bbox \
  -H "Authorization: Bearer $API_KEY"

{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "exists": true,
  "status": "succeeded",
  "group_batch_id": "bx_8a3c2e1f",
  "rows": {
    "0": {
      "invoice_number": { "x1": 0.121, "y1": 0.084, "x2": 0.312, "y2": 0.108, "unit": "normalized" },
      "total_amount": { "x1": 0.702, "y1": 0.611, "x2": 0.881, "y2": 0.639, "unit": "normalized" }
    }
  }
}

exists: false signifie qu'aucun travail bbox n'a jamais été déclenché pour ce document — un état très courant et attendu, pas une erreur. Les coordonnées sont des flottants x1/y1/x2/y2 normalisées dans la plage 0–1 (coins supérieur gauche et inférieur droit), indépendantes des dimensions réelles en pixels de l'image d'origine.

Au lieu d'interroger cet endpoint, enregistrez un webhook (voir le guide des webhooks) sur le lot du document — un travail bbox atteignant un statut terminal envoie un événement document.bbox_completed à cette même URL de callback, en plus des événements batch.completed qu'il reçoit déjà. Il n'y a pas d'étape d'enregistrement séparée pour bbox ; il réutilise le webhook existant du lot.

Obtenir le bbox en ligne avec les résultats

Au lieu des endpoints autonomes ci-dessus, vous pouvez aussi demander à l'endpoint des résultats de lot de remplir les données bbox déjà calculées avec ?include=bbox :

curl "https://imagetotable.ai/api/v1/batches/260716-4K9P/results?include=bbox" \
  -H "Authorization: Bearer $API_KEY"

Lorsque vous le faites, chaque valeur de champ dans line_items change de forme, passant d'un scalaire nu à {"value": ..., "bbox": ...}, avec bbox défini sur null si rien n'a été calculé pour ce champ :

{ "invoice_number": { "value": "INV-1042", "bbox": { "x1": 0.121, "y1": 0.084, "x2": 0.312, "y2": 0.108, "unit": "normalized" } } }

?include=bbox ne fait que lire les données qui existent déjà — il ne déclenche jamais un nouveau travail d'annotation facturable en votre nom. Si le bbox d'un champ n'a pas encore été calculé, vous obtenez null pour celui-ci, pas une facturation implicite. Déclenchez d'abord l'annotation explicitement avec POST .../bbox.

Champs qui sont entièrement un emplacement

Certains champs ne sont pas un texte avec un emplacement accessoire — l'objectif même du champ est l'emplacement (par exemple, un champ demandant de « localiser la photo d'identité » sur un document d'identité). Pour ceux-ci, la valeur revient sous la forme d'un objet plus riche, que vous ayez demandé ou non ?include=bbox, puisque l'emplacement est la réponse, et non une métadonnée facultative à son sujet :

{
  "portrait_location": {
    "type": "image_region",
    "bbox": { "x1": 0.05, "y1": 0.12, "x2": 0.28, "y2": 0.44, "unit": "normalized" },
    "image_url": "https://imagetotable.ai/api/v1/documents/3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f/image?crop=0.03%2C0.10%2C0.30%2C0.46"
  }
}

image_url pointe vers GET /documents/{document_id}/image?crop=... — un véritable JPEG recadré et récupérable de cette région (légèrement élargi par rapport aux coordonnées brutes pour qu'un recadrage serré soit moins susceptible de couper une partie de ce que vous vouliez), et non pas seulement quatre nombres que vous devriez recadrer vous-même à partir de l'image d'origine. Vous pouvez également appeler ce point de terminaison directement avec votre propre ?crop=x1,y1,x2,y2 (même convention normalisée 0–1) sur n'importe quel document, qu'il provienne ou non d'un travail bbox.

Limitation connue : les coordonnées sont issues du modèle, non vérifiées au pixel près

Les coordonnées bbox proviennent directement de l'ancrage visuel du modèle sous-jacent — il n'y a aucune étape de vérification au niveau du pixel qui vérifie si une boîte donnée est dessinée de manière serrée ou lâche autour de sa cible. Sur les documents simples et peu denses, cela est généralement suffisamment précis pour une utilisation directe. Sur les documents complexes ou très denses — tableaux avec de nombreuses colonnes, formulaires avec des champs très rapprochés — la précision diminue sensiblement, et les boîtes peuvent être trop serrées, trop lâches, ou occasionnellement faire référence au mauvais champ voisin. Ne traitez pas la sortie bbox comme une source de recadrage exacte et parfaite au pixel près — si votre flux de travail dépend d'un recadrage précis (pour l'OCR en aval, des preuves juridiques, etc.), vérifiez les résultats plutôt que de leur faire aveuglément confiance, en particulier sur les mises en page denses.

Les recadrages de commodité image_url (à la fois pour les champs d'emplacement pur et pour vos propres appels ?crop= contre une boîte dérivée de bbox) sont générés avec une petite marge autour des coordonnées rapportées, afin de réduire le risque qu'une boîte trop serrée coupe du contenu réel — il s'agit d'une mesure de tolérance, et non d'une correction de précision. Les coordonnées bbox brutes renvoyées dans le JSON lui-même sont toujours exactement celles rapportées par le modèle, sans marge.

Facturation et paramètres du compte

Le déclenchement de l'annotation bbox ne dépend pas uniquement du fait que vous appeliez vous-même les endpoints bbox. Votre compte dispose d'un paramètre — auto_annotate_bbox, configuré dans l'application web, et non via cette API — qui, lorsqu'il est activé, déclenche automatiquement (et facture) un passage bbox après chaque extraction terminée, y compris celles lancées via v1. Si ce paramètre est activé sur votre compte, vous pouvez être facturé pour l'annotation bbox sans jamais appeler vous-même POST .../bbox. Consultez Paramètres du compte et comportement de l'API pour une vue d'ensemble des paramètres au niveau du compte que l'API vous permet ou non de remplacer par requête.