L'API OCR di Mistral
In questa pagina
Aggiornato il 2 novembre 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) è stato ritirato il 30 settembre 2026. Utilizza OCR 4.1 (mistral-ocr-4-1), disponibile in versione generale dal 31 agosto allo stesso prezzo, oppure l’aliasmistral-ocr-latest, che punta ad esso dal 16 luglio. OCR 4.1 aggiunge punteggi di confidenza a livello di blocco. Addendum del 3 novembre 2026: Per inviare un PDF locale, codificalo in base64 come{"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Il tipodocument_base64presente negli esempi più vecchi non esiste nella documentazione né nell’SDKmistralai, e quegli esempi avrebbero fallito. Fonti: OCR Processor · Document QnA.
Un unico punto di ingresso
Tutta l’estrazione di documenti passa attraverso un singolo endpoint: /v1/ocr, o il suo equivalente nell’SDK Python, client.ocr.process(). Che tu stia elaborando la foto di una ricevuta o un rapporto annuale di 800 pagine, la chiamata è la stessa. Questa lezione dettaglia come configurarla, i tre modi per passarle un documento e cosa restituisce.
Installazione e configurazione
L’installazione richiede un solo comando:
pip install mistralai
Successivamente, istanzia il client con la tua chiave API:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
Questo approccio funziona per un test rapido in un notebook, ma rischi di committare accidentalmente la tua chiave. Non appena il codice lascia la tua macchina, usa una variabile d’ambiente:
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Utilizzeremo questa seconda forma in tutte le lezioni successive.
Parametri della chiamata
La chiamata client.ocr.process() richiede solo due parametri: model, sempre impostato su "mistral-ocr-latest", e document, che descrive il file da elaborare in una delle tre forme dettagliate di seguito.
Altri parametri adattano l’output alle tue esigenze:
table_format: Formato della tabella (null,"markdown","html")include_image_base64:Trueper ricevere le immagini in base64bbox_annotation_format: Schema di annotazione delle bounding boxdocument_annotation_format: Schema di annotazione completo del documentodocument_annotation_prompt: Istruzioni di alto livello per l’annotazione
I primi due riguardano l’OCR vero e proprio e li affronterai nelle prossime lezioni. Gli ultimi tre si riferiscono alle annotazioni, trattate a partire dalla Lezione 9; per ora, ricorda semplicemente che ti permettono di richiedere un’estrazione strutturata nella stessa chiamata, senza un secondo round trip.
Tre modi per inviare un documento
Il primo, un URL pubblico, è il più diretto quando il file è già accessibile online: un rapporto pubblicato, un allegato archiviato in un bucket pubblico:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
Il secondo è necessario per i documenti che risiedono sulla tua macchina o in uno storage privato. Li codifichi in base64 e li invii nel corpo della richiesta. Questo è il metodo predefinito per qualsiasi cosa confidenziale, poiché non è necessario esporre alcun 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}"
}
)
Il terzo utilizza le Files API. Carichi il file una volta, recuperi un ID e poi lo riferisci nelle tue chiamate. Il vantaggio emerge con documenti di grandi dimensioni o quando lo stesso file deve essere elaborato più volte: un’estrazione OCR oggi, un’annotazione con uno schema diverso domani; non ritrasferisci 40 MB a ogni tentativo.
# Carica il file
uploaded_file = client.files.upload(
file=open("my_document.pdf", "rb"),
purpose="ocr"
)
# Usa il file caricato
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "file_id",
"file_id": uploaded_file.id
}
)
Lettura della risposta
La risposta espone un elenco di pagine e ogni pagina porta con sé il proprio contenuto insieme ai metadati. Un ciclo minimo è sufficiente per verificare che l’estrazione sia andata a buon fine:
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}")
Prendi l’abitudine di eseguire questo tipo di ciclo su un documento campione prima di industrializzare qualsiasi cosa: ti dice in tre secondi se il conteggio delle pagine corrisponde, se le immagini sono state rilevate e se le intestazioni sono correttamente isolate dal corpo del testo.
Limiti ed errori
Tre vincoli governano l’utilizzo: massimo 50 MB per file, 1.000 pagine per documento e formati di input PDF, PNG, JPEG, AVIF, PPTX e DOCX. A ciò si aggiunge il rate limiting, con una soglia che dipende dal tuo livello di abbonamento: un punto da verificare prima di una parallelizzazione massiccia, altrimenti rischi di vedere le tue chiamate rifiutate in un burst.
Questi limiti, come gli incidenti di rete, si manifestano come eccezioni che devi catturare. Un job batch che si ferma alla fattura numero 300 perché un file supera la dimensione consentita è una perdita di tempo evitabile:
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}")
Distinguere i due livelli di eccezione è utile: SDKError ti fornisce un codice di stato su cui decidere se ritentare (un 429 dovrebbe essere ritentato dopo un ritardo, un 400 mai), mentre il blocco generico cattura problemi locali, come un file mancante o una codifica impossibile.
Punti chiave
- L’endpoint OCR è
client.ocr.process()con il modellomistral-ocr-latest - Tre metodi di invio: URL pubblico, base64, file caricato
- Parametri opzionali controllano il formato delle tabelle e l’inclusione delle immagini
- La risposta è strutturata pagina per pagina con Markdown, immagini e metadati
- Rispetta i limiti di 50 MB e 1.000 pagine per documento