API BIQE

Intégrez la reconnaissance d'écriture manuscrite avec correction LLM directement dans votre propre pipeline. Basée sur REST, réponses JSON, authentification par clé API.

L'API BIQE est conçue pour la production : vous soumettez des pages par programmation, suivez leur statut et récupérez le résultat — sans ouvrir le portail. Le traitement suit la même chaîne que le portail (détection de mise en page, reconnaissance, correction LLM, export vers PageXML/ALTO/PDF).

Authentification

Chaque requête s'authentifie avec une clé API. Vous pouvez transmettre la clé dans l'en-tête X-API-Key, ou dans un en-tête Authorization: Bearer — les deux sont acceptés. Le trafic passe par HTTPS chiffré.

X-API-Key: biqe_live_xxxxxxxxxxxxxxxxxxxxxxxx

# ou, de manière équivalente :
Authorization: Bearer biqe_live_xxxxxxxxxxxxxxxxxxxxxxxx

Gérer les clés API

Vous créez et gérez les clés vous-même dans le portail client sous Paramètres ▸ Clés API ▸ + Nouvelle clé API. Donnez un libellé à la clé. La valeur est affichée une seule fois à la création — elle ne peut plus être réaffichée ensuite. La révocation se fait sur la même page et prend effet immédiatement.

Soumettre un scan

Soumettez les pages sous forme d'archive ZIP (une image par page), dans le champ multipart scan_zip. Vous pouvez passer en option un niveau de traitement, un preset et une URL de webhook.

curl -X POST https://ocr-handwriting.online/v1/process-scan \
  -H "X-API-Key: $BIQE_API_KEY" \
  -F "scan_zip=@my-pages.zip" \
  -F "llm_tier=balanced" \
  -F "preset=generic_historical" \
  -F "webhook_url=https://your-system.example/biqe-callback"

Réponse — 202 Accepted :

{
  "job_id": "ff6f3db8-ab61-47d0-9f69-1987b5b0f2f0",
  "state": "queued",
  "page_count": 14,
  "created_at": "2026-05-02T11:56:05Z",
  "expires_at": "2026-05-09T11:56:05Z",
  "status_url": ".../v1/process-scan/ff6f3db8-...",
  "result_url": ".../v1/process-scan/ff6f3db8-.../result"
}

Suivre le statut de la tâche

Interrogez le statut, ou attendez le callback webhook (recommandé pour les volumes importants).

curl https://ocr-handwriting.online/v1/process-scan/<job_id> \
  -H "X-API-Key: $BIQE_API_KEY"

Réponse (champs selon la progression) :

{
  "job_id": "ff6f3db8-...",
  "state": "done",
  "page_count": 14,
  "current_step": "export",
  "created_at": "2026-05-02T11:56:05Z",
  "started_at": "2026-05-02T11:56:09Z",
  "finished_at": "2026-05-02T11:57:43Z",
  "expires_at": "2026-05-09T11:56:05Z",
  "error_message": null,
  "warning_message": null,
  "result_url": ".../v1/process-scan/ff6f3db8-.../result"
}

Récupérer le résultat

Dès que le statut est done, téléchargez l'archive de résultat via ce point de terminaison (ou via la result_url) : PageXML, ALTO et — si activé — un PDF interrogeable. Le lien reste disponible environ 7 jours (voir expires_at).

curl -L https://ocr-handwriting.online/v1/process-scan/<job_id>/result \
  -H "X-API-Key: $BIQE_API_KEY" \
  -o result.zip

Annuler une tâche

Une tâche encore en file d'attente ou en cours de traitement peut être annulée. Son statut passe alors à cancelled.

curl -X DELETE https://ocr-handwriting.online/v1/process-scan/<job_id> \
  -H "X-API-Key: $BIQE_API_KEY"

Callback webhook & réessais

Si vous passez une webhook_url, nous envoyons un POST en JSON dès que la tâche atteint un état final (done ou failed). Le callback porte ces en-têtes :

La charge utile :

{
  "job_id": "ff6f3db8-...",
  "state": "done",
  "page_count": 14,
  "result_url": ".../v1/process-scan/ff6f3db8-.../result"
}

result_url n'est présent que lorsque state vaut done. Les livraisons échouées sont réessayées jusqu'à cinq fois avec un back-off exponentiel (environ 1, 5, 25, 125 et 625 secondes). Votre point de terminaison doit renvoyer un 2xx aussi vite que possible et être accessible en HTTPS.

Vérifier la signature du webhook

Chaque callback est signé. La signature est un HMAC-SHA256 sur le corps brut de la requête, avec votre secret webhook propre au compte comme clé, en hex minuscule dans l'en-tête X-BIQE-Signature. Le secret (64 caractères hex) est propre au client ; récupérez-le via le portail.

import hmac, hashlib

secret = "<your-webhook-secret>".encode()
body   = request.get_data()  # raw bytes
expected = hmac.new(secret, body, hashlib.sha256).hexdigest()

if not hmac.compare_digest(expected, request.headers["X-BIQE-Signature"]):
    return "forbidden", 403

Statuts de tâche

Paramètres de process-scan

Gestion des erreurs