Démarrage rapide

Ce guide parcourt l'ensemble du processus — obtenir une clé, importer un document, lancer le traitement, récupérer les résultats — en prenant l'exemple d'une facture. Si vous n'avez pas encore installé curl ou configuré une variable d'environnement pour votre clé, consultez d'abord Configuration de l'environnement.

Étape 1 — Obtenez votre clé API

Votre clé API se trouve sur la page des paramètres de votre compte, dans la section Clé API. L'API v1 nécessite un forfait payant (Basique ou supérieur) — les clés du forfait Gratuit sont acceptées lors de la vérification d'authentification, mais chaque appel suivant renvoie une erreur plan_required. Les clés générées désormais ressemblent à itt_live_<64 caractères hexadécimaux> ; exportez la vôtre en tant que variable d'environnement pour éviter de la coder en dur dans un script :

export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Étape 2 — Importez un document

POST /api/v1/documents accepte soit un file (multipart) soit une url que le serveur récupère pour vous — transmettez exactement un seul paramètre. batch_name est facultatif — omettez-le et l'API en génère un pour vous (renvoyé dans la réponse) ; tous les documents que vous souhaitez traiter ensemble doivent partager le même batch_name. Cet exemple utilise url avec une facture exemple hébergée sur notre propre site, il est donc exécutable tel quel, sans fichier local nécessaire :

curl -X POST https://imagetotable.ai/api/v1/documents \
  -H "Authorization: Bearer $API_KEY" \
  -F "url=https://imagetotable.ai/static/samples/invoice.webp"

import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/documents",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    data={"url": "https://imagetotable.ai/static/samples/invoice.webp"},
)
print(response.json())

const formData = new FormData();
formData.append("url", "https://imagetotable.ai/static/samples/invoice.webp");

const response = await fetch("https://imagetotable.ai/api/v1/documents", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
  body: formData,
});
console.log(await response.json());

Vous avez un fichier local ? Remplacez url par un champ multipart file — consultez Importer un document dans la Référence pour la liste complète des paramètres, y compris batch_name, template_id et password.

La réponse renvoie l'ID du nouveau document et le lot dans lequel il a été placé — conservez batch_name, vous en aurez besoin dans les deux étapes suivantes :

{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "batch_name": "260716-4K9P",
  "remaining_batch_capacity": 199
}

L'import d'un PDF multipage fonctionne de la même manière qu'une image, sauf que document_id est renvoyé sous forme de tableau — un document par page — car chaque page est traitée indépendamment.

Étape 3 — Lancer le traitement

POST /api/v1/batches/{batch_name}/process déclenche l'extraction. Vous pouvez le pointer vers un Template sauvegardé via template_id, ou — comme ici — déclarer les champs souhaités directement avec fields pour une exécution ponctuelle :

curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "fields": [
          {"name": "invoice_number"},
          {"name": "invoice_date"},
          {"name": "vendor_name"},
          {"name": "total_amount"}
        ]
      }'

import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/process",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "fields": [
            {"name": "invoice_number"},
            {"name": "invoice_date"},
            {"name": "vendor_name"},
            {"name": "total_amount"},
        ]
    },
)
print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: [
      { name: "invoice_number" },
      { name: "invoice_date" },
      { name: "vendor_name" },
      { name: "total_amount" },
    ],
  }),
});
console.log(await response.json());

Cela débite les crédits immédiatement (un document débité par appel) et met le(s) document(s) en file d'attente pour un traitement en arrière-plan :

{
  "batch_name": "260716-4K9P",
  "queued": 1,
  "quality": "fast",
  "webhook_registered": false
}

Omettez complètement fields et template_id et l'API déduit elle-même des noms de colonnes raisonnables. quality est également facultatif — si vous l'omettez, le traitement utilise le réglage vitesse/qualité par défaut de votre compte (voir Paramètres du compte et comportement de l'API). webhook_registered: false signifie simplement que cet appel particulier n'incluait pas webhook_url — cela ne signifie pas qu'aucun webhook n'est enregistré pour ce lot ; consultez la référence des lots si vous en enregistrez un séparément via PUT .../webhook.

Étape 4 — Interrogez et récupérez vos résultats

Le traitement est asynchrone — interrogez GET /api/v1/batches/{batch_name} jusqu'à ce que all_done soit true (quelques secondes pour un seul document), ou enregistrez un webhook au lieu d'interroger. Le cycle de vie complet est décrit dans le guide du Modèle de tâche asynchrone.

Une fois terminé, récupérez les résultats transformés :

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

import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/results",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/results", {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());

Le JSON de réponse n'est jamais segmenté par langue — sa structure ne change pas selon le client qui a envoyé la requête :

{
  "batch_name": "260716-4K9P",
  "status": "succeeded",
  "created_at": "2026-07-16T09:12:03Z",
  "started_at": "2026-07-16T09:12:05Z",
  "completed_at": "2026-07-16T09:12:14Z",
  "documents": [
    {
      "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
      "filename": "invoice.jpg",
      "status": "succeeded",
      "created_at": "2026-07-16T09:12:03Z",
      "started_at": "2026-07-16T09:12:05Z",
      "completed_at": "2026-07-16T09:12:14Z",
      "line_items": [
        {
          "invoice_number": "INV-1042",
          "invoice_date": "2026-06-30",
          "vendor_name": "Acme Supply Co.",
          "total_amount": "1,284.50"
        }
      ]
    }
  ]
}

completed_at est défini lorsqu'un document (ou, au niveau du lot, chaque document du lot) atteint un état terminal — succeeded, failed ou canceled. Il reste null tant qu'il est queued ou processing, et au niveau du lot, il reste également null jusqu'à ce que tous les documents du lot soient terminés, même si certains se sont terminés plus tôt.

Prochaines étapes

À partir de là : lisez Modèle de tâche asynchrone pour le cycle de vie complet des statuts, Webhooks pour être notifié au lieu d'interroger, et Référence API pour la liste complète des paramètres de chaque point d'accès.