OCR

L’API OCR AlphaEdge extrait du texte exploitable à partir de fichiers dont le format est accepté par l’endpoint (voir Formats de fichiers supportés). Le service vise une bonne précision de reconnaissance et des temps de réponse adaptés aux intégrations production.

Ce document décrit le contrat de requête et de réponse (multipart, champ image), la liste canonique des extensions d’entrée, la structure JSON renvoyée et les bonnes pratiques d’intégration.

URL d’appel, hôte et documentation

Utilisez la base URL publique de la passerelle, par ex. https://api-endpoints.alphaedge-ai.com. N’appelez pas la gateway par une adresse IP seule si un nom d’hôte public est requis (sinon 403). La documentation que vous lisez est hébergée sur https://api-docs.alphaedge-ai.com/ ; la passerelle n’expose pas Swagger / OpenAPI en ligne (spécification OpenAPI désactivée côté serveur).

Slugs de modèles (OCR)

L’URL doit utiliser l’un des slugs enregistrés : alpha-digit-max ou alpha-digit-medium (kebab-case). Le catalogue GET /models renvoie model_slug et type pour chaque entrée. Un slug inconnu produit une erreur 404.

Exemple minimal : requête POST multipart avec en-tête X-API-Key et champ fichier image.

Exemple basique

import requests

url = "https://api-endpoints.alphaedge-ai.com/models/alpha-digit-max/ocr"
headers = {"X-API-Key": "TA_CLE"}

with open("/chemin/image.png", "rb") as f:
    files = {"image": ("image.png", f, "image/png")}
    r = requests.post(url, headers=headers, files=files, timeout=300)

print(r.status_code)
print(r.json())

curl https://api-endpoints.alphaedge-ai.com/models/alpha-digit-max/ocr \
  -H "X-API-Key: TA_CLE" \
  -F "image=@/chemin/image.png"

import fs from "node:fs";

const form = new FormData();
form.append("image", new Blob([fs.readFileSync("/chemin/image.png")]), "image.png");

const res = await fetch("https://api-endpoints.alphaedge-ai.com/models/alpha-digit-max/ocr", {
  method: "POST",
  headers: { "X-API-Key": "TA_CLE" },
  body: form
});

console.log(res.status, await res.json());

Paramètres applicables à l’endpoint POST /models/{model_slug}/ocr.

Le corps doit être envoyé en multipart/form-data. Le champ fichier doit porter exactement le nom image. L’identifiant du modèle se transmet uniquement dans le chemin d’URL ; un champ model dans le formulaire ou l’usage de file à la place de image n’est pas accepté et produit une réponse HTTP 422 (Unprocessable Entity).

Ne définissez pas l’en-tête Content-Type à la main pour cette requête : avec multipart, la bibliothèque HTTP doit ajouter multipart/form-data et le boundary (sinon risque d’erreurs ou de corps illisible).

Tout autre nom de champ est refusé ; ne pas envoyer de champ model dans le formulaire (le modèle est uniquement dans le chemin d’URL).

L’admission du fichier repose sur son extension : seules les valeurs ci-dessous sont reconnues par la chaîne de décodage pour cet endpoint. Toute autre extension doit être traitée comme non prise en charge.

Les formats bureautiques natifs (par exemple DOCX, XLSX, PPTX) et bases de données ne sont pas ingérés par ce service. Convertissez-les au préalable vers PDF ou vers une image parmi les formats acceptés si vous devez en extraire le texte via l’OCR.

.apng
.avif
.avifs
.blp
.bmp
.bufr
.bw
.cur
.dcx
.dds
.dib
.emf
.eps
.fit
.fits
.flc
.fli
.ftc
.ftu
.gbr
.gif
.grib
.h5
.hdf
.icb
.icns
.ico
.iim
.im
.j2c
.j2k
.jfif
.jp2
.jpc
.jpe
.jpeg
.jpf
.jpg
.jpx
.mpeg
.mpg
.mpo
.msp
.palm
.pbm
.pcd
.pcx
.pdf
.pfm
.pgm
.png
.pnm
.ppm
.ps
.psd
.pxr
.qoi
.ras
.rgb
.rgba
.sgi
.tga
.tif
.tiff
.vda
.vst
.webp
.wmf
.xbm
.xpm

Qualité des entrées et formats recommandés

• Numérisation et photos : privilégier PNG, TIFF ou JPEG en haute définition (cible indicative ≥ 300 ppp).
• Production : PNG, JPEG, WEBP, TIFF et PDF offrent en général le meilleur compromis entre interopérabilité et qualité OCR. Les autres extensions listées peuvent être décodées par le pipeline sans garantir la même pertinence pour tous les cas d’usage.
• Réduire la compression destructive et les résolutions trop faibles afin de limiter les erreurs de reconnaissance.

Réponse HTTP 200 : JSON (schéma OcrResponse). Les champs global_confidence et image_filename peuvent être null ; le champ interne gateway_wall_ms n’est pas renvoyé au client. Exemple illustratif :

{
  "model_slug": "alpha-digit-max",
  "text": "26 rue Honore de Balzac",
  "inference_seconds": 0.055,
  "global_confidence": 0.82,
  "words": [
    {
      "w": "26",
      "confidence": 1
    },
    {
      "w": "rue",
      "confidence": 0.97
    },
    {
      "w": "Honore",
      "confidence": 0.47
    },
    {
      "w": "de",
      "confidence": 0.99
    },
    {
      "w": "Balzac",
      "confidence": 0.99
    }
  ],
  "image_filename": "test_manuscrit7.png"
}

La réponse OCR inclut un score de confiance global et un score par mot. Ces valeurs sont comprises entre 0 et 1 : plus le score est proche de 1, plus le modèle est confiant dans le texte reconnu.

• global_confidence - confiance moyenne sur l'ensemble du texte extrait (ou null).
• words[].confidence - confiance associée à chaque mot détecté, utile pour repérer les zones à vérifier manuellement.

Extraction avec format structuré

Extrayez des données structurées depuis un formulaire :

import requests

url = "https://api-endpoints.alphaedge-ai.com/models/alpha-digit-max/ocr"
headers = {"X-API-Key": "TA_CLE"}

with open("/chemin/image.png", "rb") as f:
    files = {"image": ("image.png", f, "image/png")}
    r = requests.post(url, headers=headers, files=files, timeout=300)

print(r.status_code)
print(r.json())

Gestion des erreurs

Voici comment gérer les erreurs de manière appropriée :

import requests

url = "https://api-endpoints.alphaedge-ai.com/models/alpha-digit-max/ocr"
headers = {"X-API-Key": "TA_CLE"}

with open("/chemin/image.png", "rb") as f:
    files = {"image": ("image.png", f, "image/png")}
    r = requests.post(url, headers=headers, files=files, timeout=300)

print(r.status_code)
print(r.json())

import fs from "node:fs";

const form = new FormData();
form.append("image", new Blob([fs.readFileSync("/chemin/image.png")]), "image.png");

const res = await fetch("https://api-endpoints.alphaedge-ai.com/models/alpha-digit-max/ocr", {
  method: "POST",
  headers: { "X-API-Key": "TA_CLE" },
  body: form
});

console.log(res.status, await res.json());

Voici quelques cas d'usage courants pour l'API OCR :

1. Digitalisation de documents

Convertissez des documents papier en texte numérique pour archivage et recherche.

2. Extraction de données de formulaires

Extrayez automatiquement les informations de formulaires scannés (factures, contrats, etc.).

3. Reconnaissance de texte dans les images

Extrayez du texte depuis des images, captures d'écran ou photos de documents.

Limitations

• Taille maximale — 25 Mo par fichier (valeur documentée ; une limite différente peut s’appliquer selon votre offre ou votre environnement).
• Types de fichiers — Restreints aux extensions énumérées dans Formats de fichiers supportés.
• Limitation du débit — Quotas et throttling selon votre offre et la politique du service.

Bonnes pratiques d’intégration

• Viser une résolution suffisante pour les scans et clichés (par ex. ≥ 300 ppp).
• Conserver un contraste net entre le texte et l’arrière-plan sur les documents numérisés.
• Gérer explicitement les codes HTTP et les erreurs renvoyées dans le corps de réponse JSON.
• Mettre en œuvre des nouvelles tentatives avec backoff exponentiel pour les erreurs transitoires (p. ex. réponses 5xx ou surcharge).
• Mettre en cache les résultats lorsque le document source est inchangé, afin de réduire latence et coûts.
• Surveiller la consommation et les quotas conformément à votre contrat.

Pour voir tous les modèles OCR disponibles avec leurs spécifications détaillées, consultez la page Nos modèles et filtrez par type.

Référence résumée pour l’intégration (codes typiques renvoyés par la passerelle) :

Pour une liste détaillée des codes d’erreur, voir aussi Codes d’erreur.