L'API OCR de Mistral — Document AI — OCR et Intelligence Documentaire

Un point d’entrée unique

Toute l’extraction documentaire passe par un seul endpoint : /v1/ocr, ou son équivalent dans le SDK Python, client.ocr.process(). Que vous traitiez une photo de ticket de caisse ou un rapport annuel de huit cents pages, c’est le même appel. Cette leçon détaille comment le configurer, les trois façons de lui transmettre un document, et ce qu’il vous rend.

Installation et configuration

L’installation tient en une commande :

pip install mistralai

Vous instanciez ensuite le client avec votre clé API :

from mistralai import Mistral

client = Mistral(api_key="votre-cle-api")

Cette écriture convient pour un essai rapide dans un notebook, mais elle vous expose à commiter votre clé par inadvertance. Dès que le code quitte votre machine, passez par une variable d’environnement :

export MISTRAL_API_KEY="votre-cle-api"

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

C’est cette seconde forme que nous utiliserons dans toutes les leçons suivantes.

Les paramètres de l’appel

L’appel client.ocr.process() n’exige que deux paramètres : model, toujours à "mistral-ocr-latest", et document, qui décrit le fichier à traiter sous l’une des trois formes détaillées plus bas.

Les autres paramètres ajustent la sortie selon vos besoins :

table_format : format des tableaux (null, "markdown", "html")
include_image_base64 : True pour recevoir les images en base64
bbox_annotation_format : schéma d’annotation des bounding boxes
document_annotation_format : schéma d’annotation du document entier
document_annotation_prompt : instructions haut niveau pour l’annotation

Les deux premiers concernent l’OCR proprement dit, et vous les manipulerez dès les prochaines leçons. Les trois derniers relèvent des annotations, traitées à partir de la leçon 9 ; retenez pour l’instant qu’ils permettent de demander une extraction structurée dans le même appel, sans repasser par un second aller-retour.

Trois façons d’envoyer un document

La première, l’URL publique, est la plus directe quand le fichier est déjà accessible en ligne — un rapport publié, une pièce jointe stockée sur un bucket public :

ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "document_url",
        "document_url": "https://exemple.com/document.pdf"
    }
)

La deuxième s’impose pour les documents qui vivent sur votre machine ou sur un stockage privé. Vous les encodez en base64 et les transmettez dans le corps de la requête. C’est la méthode par défaut pour tout ce qui est confidentiel, puisqu’aucune URL n’a besoin d’être exposée :

import base64

with open("mon_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_base64",
        "document_base64": document_base64
    }
)

La troisième passe par l’API Files. Vous uploadez le fichier une fois, récupérez un identifiant, puis le référencez dans vos appels. L’intérêt apparaît sur les documents volumineux, ou quand le même fichier doit être traité plusieurs fois — une extraction OCR aujourd’hui, une annotation avec un autre schéma demain : vous ne retransférez pas les 40 Mo à chaque tentative.

# Upload du fichier
uploaded_file = client.files.upload(
    file=open("mon_document.pdf", "rb"),
    purpose="ocr"
)

# Utilisation du fichier uploadé
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "file_id",
        "file_id": uploaded_file.id
    }
)

Lire la réponse

La réponse expose une liste de pages, et chaque page porte son contenu ainsi que ses métadonnées. Un parcours minimal suffit à vérifier que l’extraction s’est bien passée :

for page in ocr_response.pages:
    print(f"Page {page.index}")
    print(f"Contenu : {page.markdown[:200]}...")
    print(f"Images : {len(page.images)} trouvée(s)")
    print(f"En-tête : {page.header}")
    print(f"Pied de page : {page.footer}")
    print(f"Dimensions : {page.dimensions}")

Prenez l’habitude de lancer ce genre de boucle sur un document témoin avant d’industrialiser quoi que ce soit : elle vous dit en trois secondes si le nombre de pages correspond, si les images ont été détectées et si les en-têtes sont bien isolés du corps de texte.

Limites et erreurs

Trois contraintes encadrent l’usage : 50 Mo par fichier au maximum, 1 000 pages par document, et les formats PDF, PNG, JPEG, AVIF, PPTX et DOCX en entrée. À cela s’ajoute un rate limiting dont le seuil dépend de votre tier d’abonnement — un point à vérifier avant de paralléliser massivement, sous peine de voir vos appels rejetés en rafale.

Ces limites, comme les incidents réseau, se manifestent sous forme d’exceptions qu’il faut intercepter. Un traitement de lot qui s’interrompt à la trois-centième facture parce qu’un fichier dépasse la taille autorisée est une perte de temps évitable :

from mistralai import Mistral
from mistralai.models 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://exemple.com/document.pdf"
        }
    )
except SDKError as e:
    print(f"Erreur API : {e.status_code} - {e.message}")
except Exception as e:
    print(f"Erreur inattendue : {e}")

Distinguer les deux niveaux d’exception a son utilité : SDKError vous donne un code de statut sur lequel décider s’il faut réessayer — un 429 se retente après un délai, un 400 jamais —, tandis que le bloc générique attrape les problèmes locaux, fichier introuvable ou encodage impossible.

Points clés à retenir

L’endpoint OCR est client.ocr.process() avec le modèle mistral-ocr-latest
Trois méthodes d’envoi : URL publique, base64, fichier uploadé
Les paramètres optionnels contrôlent le format des tableaux et l’inclusion des images
La réponse est structurée page par page avec Markdown, images et métadonnées
Respectez les limites de 50 Mo et 1 000 pages par document