# Zones de délimitation (bbox) — Localiser les valeurs extraites

> bbox est une seconde passe optionnelle et facturée séparément qui localise exactement sur la page d'où provient chaque valeur extraite — coordonnées directes du modèle sans vérification au niveau du pixel, donc considérez la précision comme approximative, pas exacte.

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 :

```bash
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 :

```json
{
  "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](/developers/guides/idempotency), car il s'agit d'une action payante consommant des crédits.

## Vérification du statut et des résultats

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

```json
{
  "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](/developers/guides/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` :

```bash
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 :

```json
{ "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 :

```json
{
  "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](/developers/guides/account-settings) pour une vue d'ensemble des paramètres au niveau du compte que l'API vous permet ou non de remplacer par requête.

---

Source: https://imagetotable.ai/fr/developers/guides/bbox