Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Mistralov OCR API

Lekcija 4 od 16 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Jedna ulazna točka
  2. Instalacija i konfiguracija
  3. Parametri poziva
  4. Tri načina slanja dokumenta
  5. Čitanje odgovora
  6. Ograničenja i pogreške
  7. Ključne točke

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 alias mistral-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,…"}. Tip document_base64 pronađen u starijim primjerima ne postoji u dokumentaciji niti u mistralai SDK-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: True za primanje slika u base64 formatu
  • bbox_annotation_format: Shema anotacije okvirnih polja (bounding box)
  • document_annotation_format: Shema potpune anotacije dokumenta
  • document_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 modelom mistral-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