Documentation API

/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 -X GET https://sotaocr.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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
}

/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 : fast par defaut, ou pro lorsque Pro est disponible pour votre compte.

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"

{
  "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"
}

/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 -X GET https://sotaocr.com/v1/jobs/job_123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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"
}

/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. Avant cela, l'endpoint repond avec 202 Accepted et le code result_not_ready.

• format: (Optionnel) Format de reponse : json, markdown ou text. Par defaut : json.

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

{
  "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\":{}}]}"
}

/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 -X GET https://sotaocr.com/v1/jobs/job_123456789/pages/1/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output page_0001_preview.png

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)

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.