API-ul OCR de la Mistral
Pe această pagină
Actualizat pe 2 noiembrie 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) a fost retras la 30 septembrie 2026. Utilizați OCR 4.1 (mistral-ocr-4-1), disponibil public din 31 august la același preț, sau aliasulmistral-ocr-latest, care indică spre acesta din 16 iulie. OCR 4.1 adaugă scoruri de încredere la nivel de bloc. Addendum 3 noiembrie 2026: Pentru a trimite un PDF local, codificați-l în base64 sub forma{"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Tipuldocument_base64întâlnit în exemplele mai vechi nu există nici în documentație, nici în SDK-ulmistralai, iar acele exemple ar fi eșuat. Surse: OCR Processor · Document QnA.
Un singur punct de intrare
Toate extragerile de date din documente trec printr-un singur endpoint: /v1/ocr, sau echivalentul său în SDK-ul Python, client.ocr.process(). Fie că procesați o fotografie a unui bon fiscal sau un raport anual de 800 de pagini, apelul rămâne același. Această lecție detaliază modul de configurare, cele trei metode de transmitere a unui document și structura răspunsului returnat.
Instalare și configurare
Instalarea necesită o singură comandă:
pip install mistralai
Apoi, instanțiați clientul folosind cheia dvs. API:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
Această abordare funcționează pentru un test rapid într-un notebook, dar riscați să comiteți accidental cheia în repository. De îndată ce codul părăsește mașina locală, utilizați o variabilă de mediu:
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Vom folosi această a doua formă în toate lecțiile următoare.
Parametrii apelului
Apelul client.ocr.process() necesită doar doi parametri: model, setat întotdeauna la "mistral-ocr-latest", și document, care descrie fișierul de procesat într-una dintre cele trei forme detaliate mai jos.
Alți parametri ajustează ieșirea în funcție de nevoile dumneavoastră:
table_format: Formatul tabelelor (null,"markdown","html")include_image_base64:Truepentru a primi imaginile în format base64bbox_annotation_format: Schema de adnotare a casetelor delimitatoare (bounding boxes)document_annotation_format: Schema completă de adnotare a documentuluidocument_annotation_prompt: Instrucțiuni de nivel înalt pentru adnotare
Primii doi parametri privesc OCR-ul propriu-zis și îi veți gestiona în lecțiile următoare. Ultimii trei se referă la adnotări, tratate începând cu Lecția 9; deocamdată, rețineți doar că aceștia vă permit să solicitați o extragere structurată în același apel, fără o a doua rundă de comunicare cu serverul.
Trei moduri de a trimite un document
Primul, prin URL public, este cel mai direct atunci când fișierul este deja accesibil online — un raport publicat, un atașament stocat într-un bucket public:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
Al doilea este necesar pentru documentele care se află pe mașina dumneavoastră sau într-o stocare privată. Le codificați în base64 și le trimiteți în corpul cererii. Aceasta este metoda implicită pentru orice conținut confidențial, deoarece nu este nevoie să expuneți niciun URL:
import base64
with open("my_document.pdf", "rb") as f:
document_base64 = base64.b64encode(f.read()).decode("utf-8")
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": f"data:application/pdf;base64,{document_base64}"
}
)
Al treilea utilizează API-ul Files. Încărcați fișierul o singură dată, recuperați un ID și apoi îl referenciați în apelurile dumneavoastră. Beneficiul devine vizibil în cazul documentelor mari sau când același fișier trebuie procesat de mai multe ori — o extragere OCR astăzi, o adnotare cu o schemă diferită mâine: nu mai retransmiteți 40 MB la fiecare încercare.
# Încărcarea fișierului
uploaded_file = client.files.upload(
file=open("my_document.pdf", "rb"),
purpose="ocr"
)
# Utilizarea fișierului încărcat
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "file_id",
"file_id": uploaded_file.id
}
)
Citirea răspunsului
Răspunsul expune o listă de pagini, iar fiecare pagină conține atât conținutul, cât și metadatele sale. O buclă minimală este suficientă pentru a verifica dacă extragerea s-a desfășurat corect:
for page in ocr_response.pages:
print(f"Page {page.index}")
print(f"Content: {page.markdown[:200]}...")
print(f"Images: {len(page.images)} found")
print(f"Header: {page.header}")
print(f"Footer: {page.footer}")
print(f"Dimensions: {page.dimensions}")
Obișnuiți-vă să rulați acest tip de buclă pe un document eșantion înainte de a industrializa orice proces: vă spune în trei secunde dacă numărul de pagini corespunde, dacă au fost detectate imagini și dacă anteturile sunt izolate corect de corpul textului.
Limite și erori
Trei constrângeri guvernează utilizarea: maximum 50 MB per fișier, 1.000 de pagini per document și formatele de intrare PDF, PNG, JPEG, AVIF, PPTX și DOCX. Peste acestea se adaugă limitarea ratei de apeluri (rate limiting), cu un prag care depinde de nivelul abonamentului dumneavoastră — un aspect de verificat înainte de o paralelizare masivă, altfel riscați să vedeți apelurile respinse în rafală.
Aceste limite, la fel ca incidentele de rețea, se manifestă prin excepții pe care trebuie să le gestionați. Un job batch care se oprește la factura numărul 300 deoarece un fișier depășește dimensiunea permisă reprezintă o pierdere de timp evitabilă:
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
try:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
except SDKError as e:
print(f"API Error: {e.status_code} - {e.message}")
except Exception as e:
print(f"Unexpected error: {e}")
Distingerea celor două niveluri de excepții este utilă: SDKError vă oferă un cod de status pe baza căruia decideți dacă să reîncercați — un 429 trebuie reîncercat după o pauză, un 400 niciodată — în timp ce blocul generic captează probleme locale, cum ar fi un fișier lipsă sau o codificare imposibilă.
Puncte cheie
- Endpoint-ul OCR este
client.ocr.process()cu modelulmistral-ocr-latest - Trei metode de trimitere: URL public, base64, fișier încărcat
- Parametrii opționali controlează formatul tabelelor și includerea imaginilor
- Răspunsul este structurat pagină cu pagină, conținând Markdown, imagini și metadate
- Respectați limitele de 50 MB și 1.000 de pagini per document