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’APIDé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.
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.txtPré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.orgLa 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.orgEnvoyer 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-01https://docsaid.org/api/v1/models/docaligner/predictExaminer 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-01Le 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 0Une 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étraitementEntré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ète3. 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 completNouvelles 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.
| HTTP | Signification / action |
|---|---|
| 400 | L’image ne peut pas être décodée. Vérifiez le fichier et envoyez une image valide. |
| 401 | La 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é. |
| 403 | La clé n’autorise pas ce modèle, ou le compte est suspendu. Vérifiez les accès de la clé dans la console. |
| 409 | Cet 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. |
| 413 | L’image dépasse la taille ou les dimensions autorisées. Choisissez une image plus petite. |
| 415 | Utilisez une image JPEG, PNG ou WebP non animée. |
| 422 | Aucun résultat valide n’a été trouvé, ou un champ est incorrect. Vérifiez les données et réessayez. |
| 429 | Votre quota ou la limite de requêtes simultanées est atteint. Vérifiez votre utilisation et patientez avant de réessayer. |
| 503 | Le service est occupé ou temporairement indisponible. Réessayez plus tard. |
| 504 | Le 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èteDocAligner 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