OCR API od Mistralu
Na této stránce
Aktualizováno 2. listopadu 2026 — OCR. Verze OCR 4.0 (
mistral-ocr-4-0) byla 30. září 2026 vyřazena z provozu. Používej OCR 4.1 (mistral-ocr-4-1), které je obecně dostupné od 31. srpna za stejnou cenu, nebo aliasmistral-ocr-latest, který na něj odkazuje od 16. července. OCR 4.1 přidává skóre spolehlivosti na úrovni bloků. Dodatek ze 3. listopadu 2026: Chcete-li odeslat místní soubor PDF, zakódujte jej do formátu base64 jako{"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Typdocument_base64nalezený ve starších příkladech v dokumentaci ani v SDKmistralaineexistuje a tyto příklady by selhaly. Zdroje: OCR Processor · Document QnA.
Jediný vstupní bod
Veškerá extrakce dokumentů probíhá přes jediný koncový bod: /v1/ocr, nebo jeho ekvivalent v Python SDK, client.ocr.process(). Ať už zpracováváš fotografii účtenky, nebo výroční zprávu o 800 stranách, volání vypadá stejně. Tato lekce podrobně popisuje, jak ji nakonfigurovat, tři způsoby předání dokumentu a co přesně vrátí.
Instalace a konfigurace
Instalace zabere jediný příkaz:
pip install mistralai
Dále inicializuj klienta pomocí svého API klíče:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
Tento přístup funguje pro rychlý test v notebooku, ale riskuješ, že klíč omylem odešleš do verze. Jakmile kód opustí tvůj počítač, použij proměnnou prostředí:
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Ve všech následujících lekcích budeme používat právě tuto druhou formu.
Parametry volání
Volání client.ocr.process() vyžaduje pouze dva parametry: model, který vždy nastavíš na "mistral-ocr-latest", a document, který popisuje zpracovávaný soubor jedním ze tří níže uvedených způsobů.
Ostatní parametry upravují výstup podle tvých potřeb:
table_format: Formát tabulek (null,"markdown","html")include_image_base64:Truepro přijímání obrázků v base64bbox_annotation_format: Schéma anotací ohraničujících rámečkůdocument_annotation_format: Schéma anotací celého dokumentudocument_annotation_prompt: Pokyny vysoké úrovně pro anotaci
První dva se týkají vlastního OCR a budeš se jim věnovat v dalších lekcích. Poslední tři souvisejí s anotacemi, kterými se začneme zabývat od lekce 9; zatím si jen zapamatuj, že ti umožňují požadovat strukturovanou extrakci v rámci stejného volání, bez nutnosti druhého round-tripu.
Tři způsoby odeslání dokumentu
První, veřejná URL, je nejpřímější, když je soubor již dostupný online – například publikovaná zpráva nebo příloha uložená ve veřejném úložišti:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
Druhý způsob je nezbytný pro dokumenty, které žijí na tvém stroji nebo v soukromém úložišti. Zakóduješ je do base64 a odešleš v těle požadavku. Toto je výchozí metoda pro cokoli důvěrného, protože není třeba vystavovat žádnou 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}"
}
)
Třetí způsob využívá Files API. Soubor jednou nahraješ, získáš jeho ID a poté na něj v dalších voláních odkazuješ. Výhoda se projeví u velkých dokumentů nebo když musí být stejný soubor zpracován vícekrát – dnes extrakce OCR, zítra anotace s jiným schématem: nemusíš při každém pokusu znovu přenášet 40 MB.
# Nahrání souboru
uploaded_file = client.files.upload(
file=open("my_document.pdf", "rb"),
purpose="ocr"
)
# Použití nahraného souboru
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "file_id",
"file_id": uploaded_file.id
}
)
Čtení odpovědi
Odpověď obsahuje seznam stránek a každá stránka nese svůj obsah spolu s metadaty. K ověření, že extrakce proběhla hladce, stačí jednoduchá smyčka:
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}")
Zvykni si spouštět tento typ smyčky na vzorkovém dokumentu předtím, než něco industrializuješ: během tří sekund ti řekne, zda souhlasí počet stránek, zda byly detekovány obrázky a zda jsou záhlaví správně oddělena od hlavního textu.
Limity a chyby
Používání řídí tři omezení: maximálně 50 MB na soubor, 1 000 stránek na dokument a vstupní formáty PDF, PNG, JPEG, AVIF, PPTX a DOCX. K tomu přistupuje omezování rychlosti (rate limiting) s prahem závislým na úrovni tvého předplatného – to si ověř před masivní paralelizací, jinak riskuješ, že ti budou volání hromadně odmítána.
Tyto limity, stejně jako výpadky sítě, se projevují jako výjimky, které musíš zachytit. Dávková úloha, která se zastaví u faktury číslo 300, protože jeden soubor překračuje povolenou velikost, je zbytečnou ztrátou času, které se lze vyhnout:
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}")
Rozlišení těchto dvou úrovní výjimek je užitečné: SDKError ti poskytne stavový kód, podle kterého se rozhodneš, zda opakovat pokus – kód 429 by se měl po prodlevě zopakovat, kód 400 nikdy – zatímco obecný blok zachytí lokální problémy, jako je chybějící soubor nebo nemožné kódování.
Klíčové poznatky
- Koncový bod OCR je
client.ocr.process()s modelemmistral-ocr-latest - Tři metody odeslání: veřejná URL, base64, nahraný soubor
- Volitelné parametry řídí formát tabulek a zahrnutí obrázků
- Odpověď je strukturována po stránkách s Markdownem, obrázky a metadaty
- Respektuj limity 50 MB a 1 000 stránek na dokument