Pour commencer

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 atterri — conservez batch_name, vous en aurez besoin aux deux étapes suivantes :

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

L'envoi d'un PDF multipage — ou d'un fichier Word (.docx) ou texte brut (.txt), tous deux convertis en PDF côté serveur au préalable — au lieu d'une image fonctionne de la même manière, sauf que document_id revient sous forme de tableau — un document par page — puisque 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 modèle enregistré via template_id, ou — comme ici — déclarer les champs souhaités en ligne 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éduit immédiatement des Credits — 1 crédit par document mis en file d'attente pour la plupart des comptes, plus si votre compte s'est vu attribuer un niveau de modèle supérieur — 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
}

Laissez fields et template_id de côté et l'API déduit elle-même des noms de colonnes raisonnables. quality est aussi facultatif — omettez-le et le traitement revient au réglage de vitesse/qualité de votre compte (voir Account Settings and API Behavior). webhook_registered: false ici signifie simplement que cet appel particulier n'incluait pas webhook_url — cela ne veut pas dire qu'aucun webhook n'est enregistré pour ce lot ; consultez la référence Batches 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 couvert dans le guide Async Task Model.

Une fois terminé, récupérez les résultats restructuré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 — la structure ne change pas selon le client qui a envoyé la requête :

{
  "batch_name": "260716-4K9P",
  "status": "succeeded",
  "merge_active": false,
  "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 aussi null jusqu'à ce que tous les documents du lot soient terminés, même si certains d'entre eux 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.

📮 contact email: [email protected]