Mistralov OCR API
Na ovoj stranici
Ažurirano 2. studenoga 2026. — OCR. Verzija OCR 4.0 (
mistral-ocr-4-0) povučena je iz upotrebe 30. rujna 2026. Koristi OCR 4.1 (mistral-ocr-4-1), koji je općenito dostupan od 31. kolovoza po istoj cijeni, ili aliasmistral-ocr-latest, koji na njega pokazuje od 16. srpnja. OCR 4.1 dodaje ocjene pouzdanosti na razini blokova. Dodatak 3. studenoga 2026.: Za slanje lokalnog PDF-a, kodiraj ga u base64 kao{"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Tipdocument_base64pronađen u starijim primjerima ne postoji u dokumentaciji niti umistralaiSDK-u, a ti bi primjeri bili neuspješni. Izvori: OCR Processor · Document QnA.
Jedna ulazna točka
Sva ekstrakcija dokumenata prolazi kroz jednu krajnju točku: /v1/ocr, ili njezin ekvivalent u Python SDK-u, client.ocr.process(). Bilo da obrađuješ fotografiju računa ili godišnje izvješće od 800 stranica, poziv je isti. Ova lekcija detaljno objašnjava kako ga konfigurirati, tri načina prosljeđivanja dokumenta i što on vraća.
Instalacija i konfiguracija
Instalacija zahtijeva samo jednu naredbu:
pip install mistralai
Zatim inicijaliziraj klijent sa svojim API ključem:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
Ovaj pristup funkcionira za brzo testiranje u bilježnici, ali nosi rizik slučajnog objavljivanja tvog ključa. Čim kod napusti tvoje računalo, koristi varijablu okruženja:
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
U svim ćemo narednim lekcijama koristiti ovaj drugi oblik.
Parametri poziva
Poziv client.ocr.process() zahtijeva samo dva parametra: model, koji uvijek postavljaš na "mistral-ocr-latest", i document, koji opisuje datoteku za obradu u jednom od tri dolje navedena oblika.
Ostali parametri prilagođavaju izlaz tvojim potrebama:
table_format: Format tablice (null,"markdown","html")include_image_base64:Trueza primanje slika u base64 formatubbox_annotation_format: Shema anotacije okvirnih polja (bounding box)document_annotation_format: Shema potpune anotacije dokumentadocument_annotation_prompt: Upute visoke razine za anotaciju
Prva dva odnose se na sam OCR i njima ćeš se baviti u sljedećim lekcijama. Posljednja tri odnose se na anotacije, koje su obrađene počevši od lekcije 9; za sada samo zapamti da ti omogućuju zahtijevanje strukturirane ekstrakcije u istom pozivu, bez dodatnog povratnog puta (round trip).
Tri načina slanja dokumenta
Prvi, javni URL, najizravniji je kada je datoteka već dostupna na internetu – objavljeno izvješće, privitak pohranjen u javnom spremištu:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
Drugi je nužan za dokumente koji se nalaze na tvojem računalu ili u privatnom spremištu. Kodiraš ih u base64 i šalješ u tijelu zahtjeva. Ovo je zadana metoda za sve povjerljivo, jer nije potrebno izlagati nikakav 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}"
}
)
Treći koristi Files API. Datoteku učitaš jednom, dobiješ ID, a zatim se na njega pozivaš u svojim pozivima. Prednost se očituje kod velikih dokumenata ili kada se ista datoteka mora obraditi više puta – ekstrakcija OCR-om danas, anotacija s drugačijom shemom sutra: ne prenosiš ponovno 40 MB pri svakom pokušaju.
# Učitaj datoteku
uploaded_file = client.files.upload(
file=open("my_document.pdf", "rb"),
purpose="ocr"
)
# Koristi učitanu datoteku
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "file_id",
"file_id": uploaded_file.id
}
)
Čitanje odgovora
Odgovor izlaže popis stranica, a svaka stranica nosi svoj sadržaj zajedno s metapodacima. Minimalna petlja dovoljna je za provjeru je li ekstrakcija prošla glatko:
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}")
Uvedi naviku pokretanja ovakve petlje na uzorku dokumenta prije industrijske primjene: u tri sekunde ti govori odgovara li broj stranica, jesu li slike otkrivene i jesu li zaglavlja pravilno odvojena od glavnog teksta.
Ograničenja i pogreške
Tri ograničenja upravljaju korištenjem: maksimalno 50 MB po datoteci, 1.000 stranica po dokumentu i ulazni formati PDF, PNG, JPEG, AVIF, PPTX i DOCX. Uz to dolazi i ograničenje stope (rate limiting), s pragom koji ovisi o tvojoj razini pretplate – točku koju trebaš provjeriti prije masovne paralelizacije, inače riskiraš da ti pozivi budu odbijeni u naletu.
Ova se ograničenja, kao i mrežni incidenti, manifestiraju kao iznimke koje moraš uhvatiti. Grupni posao koji staje na računu broj 300 jer jedna datoteka premašuje dopuštenu veličinu izbjegljiv je gubitak vremena:
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}")
Razlikovanje dviju razina iznimki korisno je: SDKError daje ti statusni kod na temelju kojeg odlučiš hoćeš li ponoviti pokušaj – na 429 trebaš ponoviti nakon kašnjenja, na 400 nikada – dok generički blok hvata lokalne probleme, poput nedostajuće datoteke ili nemogućeg kodiranja.
Ključne točke
- OCR krajnja točka je
client.ocr.process()s modelommistral-ocr-latest - Tri metode slanja: javni URL, base64, učitanu datoteku
- Opcionalni parametri kontroliraju format tablice i uključivanje slika
- Odgovor je strukturiran stranica po stranica s Markdownom, slikama i metapodacima
- Poštuj ograničenja od 50 MB i 1.000 stranica po dokumentu