Guide de l’API hébergée · Bêta gratuite

Votre première requête API.

Détectez les contours des documents avec DocAligner ou lisez les zones de lecture automatique avec MRZScanner. Choisissez un modèle et suivez l’exemple ci-dessous.

1. Créer une clé d’API

Connectez-vous à la console, nommez votre clé et sélectionnez « Créer une clé ». Enregistrez la clé complète dès son apparition : elle ne s’affiche qu’une fois. Les clés expirent après 90 jours et peuvent être révoquées à tout moment.

Choisissez les modèles accessibles avec cette clé. Les clés DocAligner existantes conservent leurs accès actuels.

Clés d’API

Définissez DOCSAID_API_KEY dans l’environnement de votre serveur ou de votre terminal. Ne l’intégrez jamais au code du navigateur ni à un dépôt public. Les clés d’API du produit sont distinctes de votre session Clerk.

2. Envoyer une image

Envoyez une requête POST multipart avec un champ file. Formats acceptés : JPEG, PNG ou WebP non animé ; maximum 768 KiB, 4 millions de pixels et 4096 pixels par côté. Le champ facultatif do_center_crop=true limite la détection au carré central.

  1. Préparation initiale

    Utilisez Python 3.12. Téléchargez le client et la liste des dépendances dans un même dossier local, puis exécutez ces commandes depuis ce dossier. Les messages du client sont en anglais. Vous pouvez commencer avec l’image d’exemple.

    python3 -m venv .venv
    .venv/bin/python -m pip install -r requirements.txt
  2. Préparer une nouvelle tâche

    Placez l’image dans document.jpg, ou adaptez le nom. Cette étape crée docaligner-job-01 avec l’entrée préparée, les options fixes et un nouvel identifiant d’opération. Vérifiez input.jpg avant l’envoi. Chaque nouvelle image ou configuration nécessite un autre dossier ; aucun dossier existant n’est écrasé.

    .venv/bin/python docsaid-client.py new document.jpg --model docaligner --job docaligner-job-01 --origin https://docsaid.org

    La préparation applique l’orientation EXIF, remplace la transparence par du blanc, limite le grand côté à 1 600 px et compresse sous 768 Kio. Entrées acceptées : JPEG/PNG/WebP fixes, 10 Mio et 40 millions de pixels au maximum. Vérifiez la lisibilité du texte après réduction.

    Réutiliser l’entrée exacte de la démo

    Téléchargez l’entrée traitée de la démo et utilisez --prepared pour conserver exactement son JPEG. Les encodeurs Python et navigateur peuvent produire des octets différents à partir de l’original. Reprenez les options avec --center-crop, --doc-align ou --raw-mrz. Utilisez ce même dossier pour send et inspect.

    .venv/bin/python docsaid-client.py new docsaid-input.jpg --prepared --model docaligner --job docaligner-demo-01 --origin https://docsaid.org
  3. Envoyer une fois et conserver la réponse

    Le client demande la clé en saisie masquée ou lit DOCSAID_API_KEY si elle est définie. Il ne l’enregistre pas et ne suit ni redirection ni relance automatique. Il affiche le statut HTTP, le Request ID et le code de cause, puis conserve reçu et réponse dans le dossier attempts de la tâche.

    .venv/bin/python docsaid-client.py send docaligner-job-01

    https://docsaid.org/api/v1/models/docaligner/predict

  4. Examiner le résultat obtenu

    Après HTTP 200, inspect crée overlay.png à côté de response.json. Comparez-le à input.jpg pour vérifier les quatre coins. MRZScanner affiche aussi les lignes et l’option de post-traitement ; vérifiez chaque champ avec l’original. Les coordonnées portent sur l’entrée préparée. Le contrôle de format ne vérifie pas l’authenticité du document.

    .venv/bin/python docsaid-client.py inspect docaligner-job-01
Reprendre une tâche interrompue

Si la réponse manque, recherchez d’abord l’identifiant de job.json dans la console. retry renvoie une fois les mêmes image, version, options et identifiant. Une tâche déjà acceptée renvoie 409 et son Request ID. Le texte reconnu est conservé uniquement dans votre réponse locale. S’il est perdu, créez une nouvelle tâche seulement pour recalculer volontairement. Toute modification d’entrée exige une nouvelle tâche.

Rechercher par identifiant d’opération ou de requête
.venv/bin/python docsaid-client.py retry docaligner-job-01

Le dossier contient l’image et les résultats reconnus. Gardez-le privé et supprimez-le quand il devient inutile. Pour l’assistance, partagez l’identifiant ou le reçu de diagnostic, sans image ni texte reconnu.

Exemples HTTP pour un client existant

Les étapes de préparation et de requête sont séparées. L’exemple curl utilise Bash, curl 7.76+, cat, awk et Python 3.12 pour créer l’identifiant. L’exemple Python utilise requests. Sous Windows, suivez le parcours PowerShell complet ci-dessus. Conservez image, options et fichier d’opération pour une relance.

export DOCSAID_API_KEY='YOUR_API_KEY'

Définissez DOCSAID_API_KEY dans l’environnement de votre serveur ou de votre terminal. Ne l’intégrez jamais au code du navigateur ni à un dépôt public. Les clés d’API du produit sont distinctes de votre session Clerk.

Utilisez un dossier par nouvelle tâche. Cette commande crée le fichier ID sans écraser un fichier existant. Les deux exemples le relisent à chaque tentative. Conservez-le avec l’entrée et les réglages.

python3 -c 'import uuid; from pathlib import Path; f = Path("docsaid-operation-id.txt").open("x"); f.write(str(uuid.uuid4())); f.close()'
DOCSAID_OPERATION_ID=$(cat docsaid-operation-id.txt)
DOCSAID_CURL_STATUS=0
curl --fail-with-body --connect-timeout 10 --max-time 30 'https://docsaid.org/api/v1/models/docaligner/predict' \
  --dump-header docsaid-response.headers --output docsaid-response.json \
  --write-out 'HTTP %{http_code}\n' \
  -H "Authorization: Bearer ${DOCSAID_API_KEY:?Set DOCSAID_API_KEY first}" \
  -H "Idempotency-Key: ${DOCSAID_OPERATION_ID:?Create an operation ID first}" \
  -F 'model_version=docaligner-1.1.1-fastvit-sa24-7f9f5a89' \
  -F 'do_center_crop=false' \
  -F '[email protected]' || DOCSAID_CURL_STATUS=$?
awk 'tolower($0) ~ /^(http|x-request-id:|x-error-code:|retry-after:)/' docsaid-response.headers
test "$DOCSAID_CURL_STATUS" -eq 0

Une réponse réussie contient polygon (les coordonnées des quatre coins), les dimensions de l’image, model_version et request_id.

JPEG / PNG / WebP · maximum 768 KiB, 4 MP et 4096 px par côté. Les deux modèles partagent le quota du compte.

Entrée et prétraitement

Entrée et prétraitement

JPEG / PNG / WebP · maximum 768 KiB, 4 MP et 4096 px par côté. Les deux modèles partagent le quota du compte.

La démo accepte 10 MiB, applique l’orientation EXIF, réduit le grand côté à 1600 px, compose sur fond blanc et encode en JPEG aux qualités 0,92, 0,80, 0,65, 0,45 puis 0,25 jusqu’à 768 KiB. Les sources de plus de 40 millions de pixels sont refusées. Téléchargez l’entrée traitée pour retrouver les octets exacts. L’API normalise EXIF et couleur mais ne réduit pas les images trop grandes.

Contrat de réponse

La console membre fournit la référence OpenAPI complète : valeurs par défaut, types et unités, champs nullables, exemples synthétiques et gestion des codes d’erreur. Connectez-vous pour la télécharger et intégrer votre client.

Se connecter pour obtenir la référence complète
Limites de la bêta

3. Consulter l’utilisation

La console affiche les 30 dernières requêtes acceptées et le quota actuel de votre compte, partagé entre l’API et l’espace d’essai. Seules les requêtes réussies consomment le quota de succès ; les tentatives acceptées sont aussi limitées par jour. Une requête en cours réserve une unité, avec au plus une requête en cours par compte.

Les quotas quotidiens sont réinitialisés à 00:00 UTC. Une requête est rattachée au jour UTC de son acceptation. Les administrateurs peuvent modifier les quotas ou réinitialiser immédiatement l’utilisation gratuite, sans supprimer l’historique. Une requête déjà en cours conserve sa réservation jusqu’à sa fin.

L’application ne conserve ni les images envoyées ni les résultats des modèles.

Rechercher une requête par son identifiant complet

Nouvelles tentatives et erreurs

Pour éviter les doublons, envoyez un Idempotency-Key unique par nouvelle opération : 1–64 lettres, chiffres, points, tirets bas, deux-points ou tirets. Réutiliser une clé déjà acceptée renvoie 409 sans relancer le modèle. Cette protection couvre toutes les clés d’API et les essais du compte. Les résultats ne sont pas renvoyés à nouveau, car ils ne sont pas conservés.

X-Error-Code distingue les moteurs occupés, les limites de fréquence, les limites quotidiennes et les résultats incertains. Respectez Retry-After, limitez les tentatives et espacez-les progressivement. Vérifiez l’utilisation avant de réessayer un résultat incertain. La limite quotidienne est réinitialisée à 00:00 UTC.

HTTPSignification / action
400L’image ne peut pas être décodée. Vérifiez le fichier et envoyez une image valide.
401La clé d’API est absente, invalide, expirée ou révoquée. Vérifiez l’en-tête Authorization ou créez une nouvelle clé.
403La clé n’autorise pas ce modèle, ou le compte est suspendu. Vérifiez les accès de la clé dans la console.
409Cet Idempotency-Key a déjà été accepté. Le modèle n’est pas relancé et le résultat précédent n’est pas conservé. Consultez l’utilisation avant une nouvelle opération.
413L’image dépasse la taille ou les dimensions autorisées. Choisissez une image plus petite.
415Utilisez une image JPEG, PNG ou WebP non animée.
422Aucun résultat valide n’a été trouvé, ou un champ est incorrect. Vérifiez les données et réessayez.
429Votre quota ou la limite de requêtes simultanées est atteint. Vérifiez votre utilisation et patientez avant de réessayer.
503Le service est occupé ou temporairement indisponible. Réessayez plus tard.
504Le délai de la requête est dépassé. Vérifiez votre utilisation avant de réessayer : le résultat peut être indéterminé.

Un délai dépassé ou une réponse interrompue peut laisser le résultat indéterminé. Après deux minutes, les requêtes inachevées passent à cet état lors de l’actualisation de l’utilisation. Vérifiez l’utilisation avant de réessayer. Conservez l’en-tête X-Request-ID pour l’assistance. Aucune requête bêta n’est facturée.

Se connecter pour obtenir la référence complète

DocAligner et MRZScanner sont disponibles via l’API et l’espace d’essai. Les requêtes bêta sont gratuites, sans configuration de paiement.

État du service et évolutions de l’APIConsole