API publique

Documentation API

Integrez SotaOCR dans vos agents IA et vos pipelines LLM. L'API fonctionne de facon asynchrone : vous televersez un document, interrogez le statut du job, puis recuperez le resultat final ou, si necessaire, l'image preview de page dans le meme espace de coordonnees que les OCR bbox.

URL de base

Tous les endpoints OCR publics sont servis depuis cet hote.

https://sotaocr.com

Authentification

Toutes les requetes API exigent un token Bearer. Vous pouvez creer une cle API dans votre dashboard.

En-tete

Authorization: Bearer YOUR_API_KEY

Routes disponibles

Le service OCR expose les routes API : /v1/balance, /v1/extract, /v1/jobs/{job_id}, /v1/jobs/{job_id}/result, /v1/jobs/{job_id}/result.html, /v1/jobs/{job_id}/result.docx et /v1/jobs/{job_id}/pages/{page_number}/preview. Lisez model_profiles avec GET /api/v1/info avant d envoyer model_profile. Les exports de reconstruction HTML et DOCX sont disponibles pour les jobs FAST et PRO.

Pretraitement OCR

Avant l'OCR principal, le service detecte automatiquement l'orientation de la page, la fait pivoter et applique un document unwarping seulement si necessaire. L'angle detecte est renvoye dans doc_preprocessor_res.angle, et l'endpoint preview renvoie l'image exacte dont l'espace de coordonnees correspond aux OCR bbox.

Polling et disponibilite

Interrogez l'API au maximum une fois par seconde. Tant que l'OCR n'est pas termine, GET /v1/jobs/{job_id}/result renvoie 202 Accepted avec le code result_not_ready.

Pro OCR

Lorsque le modele Pro est active, envoyez model_profile=pro sur /v1/extract pour utiliser un OCR de meilleure qualite. Pro OCR coute 2 scan pages pour chaque page de document traitee.

cURL · Requete Pro

curl -X POST https://sotaocr.com/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'page_ranges=[{"start":1,"end":5}]' \
  -F "model_profile=pro"

JSON · Reponse

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "pending",
  "page_count": 5,
  "pages_completed": 0,
  "model_profile": "pro",
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:00Z"
}

GET

Verifier le solde de pages

/v1/balance Retourne le solde actuel de scan pages du compte authentifie. Utilisez remaining_pages ou total_affordable_pages pour decider combien de pages peuvent encore etre traitees.

cURL · Requete

curl -X GET https://sotaocr.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON · Reponse

{
  "entity_code": "scan_page",
  "remaining_pages": 63,
  "total_affordable_pages": 63,
  "monthly_pages": {"total": 40, "allocated": 5, "remaining": 35},
  "lifetime_pages": {"total": 20, "allocated": 2, "remaining": 18},
  "tokens": {"total": 120, "allocated": 20, "remaining": 100, "affordable_pages": 10},
  "token_price": 10
}

POST

1. Televerser un document

/v1/extract Televerse un PDF ou une image pour l'OCR. En cas de succes, l'API renvoie 202 Accepted avec des metadonnees du job comme account_id, upstream_job_id, created_at et updated_at.

file: Fichier du document (PDF, PNG, JPG).
page_ranges: (Optionnel) Chaine JSON avec un tableau de plages de pages. Exemple : '[{"start":1,"end":3}]'
model_profile: Profil de modele OCR facultatif. Omettez ce champ pour utiliser le defaut du service, ou envoyez une valeur renvoyee dans model_profiles par GET /api/v1/info.

cURL · Requete

curl -X POST https://sotaocr.com/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'page_ranges=[{"start":1,"end":5}]'

JSON · Reponse

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "pending",
  "page_count": 5,
  "pages_completed": 0,
  "model_profile": "fast",
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:00Z"
}

GET

2. Verifier le statut

/v1/jobs/{job_id} Retourne 200 OK avec le statut courant ainsi que account_id, upstream_job_id, page_count, pages_completed, created_at et updated_at.

cURL · Requete

curl -X GET https://sotaocr.com/v1/jobs/job_123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON · Reponse

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "completed",
  "page_count": 5,
  "pages_completed": 5,
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:08Z"
}

GET

3. Recuperer le resultat

/v1/jobs/{job_id}/result?format=markdown Retourne 200 OK avec le contenu extrait lorsque le job est completed. Pour format=json, chaque page peut inclure doc_preprocessor_res avec angle et page_preview avec les metadonnees de l espace de coordonnees des bbox. format=html retourne le HTML reconstruit dans l enveloppe JSON et est actuellement FAST uniquement ; pour un fichier HTML autonome avec images integrees, utilisez /result.html. Avant la fin, l endpoint repond 202 Accepted avec le code result_not_ready.

format: (Optionnel) Format de reponse : json, markdown, text ou html. Par defaut json. html est actuellement FAST uniquement.

cURL · Requete

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result?format=markdown" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON · Reponse

{
  "job_id": "job_123456789",
  "format": "json",
  "page_count": 1,
  "content": "{\"job_id\":\"job_123456789\",\"page_count\":1,\"pages\":[{\"page_number\":1,\"status\":\"completed\",\"text\":\"Ivan Matveev\",\"doc_preprocessor_res\":{\"angle\":0,\"model_settings\":{\"use_doc_orientation_classify\":true,\"use_doc_unwarping\":false}},\"page_preview\":{\"coordinate_space\":\"doc_preprocessed\",\"content_type\":\"image/png\",\"width\":1192,\"height\":1684},\"raw_result\":{}}]}"
}

GET

4. Recuperer le HTML autonome

/v1/jobs/{job_id}/result.html Retourne une reconstruction text/html avec images data-URI integrees pour les jobs FAST et PRO.

cURL · Requete

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result.html" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.html

JSON · Reponse

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Disposition: inline; filename="job_123456789.html"

(HTML autonome avec images data-URI integrees)

GET

5. Recuperer la reconstruction DOCX

/v1/jobs/{job_id}/result.docx Retourne un .docx binaire avec reconstruction visuelle, images de pages integrees et texte OCR consultable pour les jobs FAST et PRO.

cURL · Requete

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result.docx" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.docx

JSON · Reponse

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="job_123456789.docx"

(octets DOCX binaires)

GET

6. Recuperer la preview de page pour les overlays bbox

/v1/jobs/{job_id}/pages/{page_number}/preview Renvoie l'image PNG de la page apres rotation automatique et unwarping optionnel. C'est l'image exacte a utiliser derriere les OCR bbox.

cURL · Requete

curl -X GET https://sotaocr.com/v1/jobs/job_123456789/pages/1/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output page_0001_preview.png

JSON · Reponse

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: inline; filename="page_0001_preview.png"

(octets PNG binaires dans le meme espace de coordonnees que les OCR bbox)

Erreurs API

La plupart des erreurs utilisent {"error":{"code":"...","message":"..."}}. insufficient_balance inclut aussi entity_code, requested_units et available_units.

400 Requete invalide: Multipart invalide, file manquant, page_ranges invalide ou PDF invalide. Code : bad_request.
401 Non autorise: Le token Bearer manque ou est invalide. Code : unauthorized.
403 Interdit: Acces API requis ou solde insuffisant. Codes : api_access_required ou insufficient_balance.
404 Introuvable: job_id inconnu ou acces a un job d'un autre compte. Code : job_not_found.
415 Media non pris en charge: Type de fichier televerse non pris en charge. Code : unsupported_media.
502 Upstream indisponible: L'upstream OCR est indisponible ou la synchronisation du job a echoue. Code : upstream_unavailable.

Pret pour l'integration ?

Creez une cle API dans le dashboard et obtenez des pages gratuites pour vos tests.

Ouvrir le dashboard Obtenir l'acces API Telecharger le skill