Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Mistral OCR API

Nodarbība 4 no 16 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Un point d’entrée unique
  2. Installation et configuration
  3. Paramètres d’appel
  4. Trois façons d’envoyer un document
  5. Lecture de la réponse
  6. Limites et erreurs
  7. Galvenās atziņas

Mise à jour du 2 novembre 2026 — OCR. OCR 4.0 (mistral-ocr-4-0) a été retiré le 30 septembre 2026. Utilise OCR 4.1 (mistral-ocr-4-1), disponible généralement depuis le 31 août au même tarif, ou l’alias mistral-ocr-latest qui le cible depuis le 16 juillet. OCR 4.1 ajoute des scores de confiance au niveau des blocs. Addendum du 3 novembre 2026 : Pour envoyer un PDF local, encode-le en base64 sous la forme {"type": "document_url", "document_url": "data:application/pdf;base64,…"}. Le type document_base64 présent dans d’anciens exemples n’existe ni dans la documentation ni dans le SDK mistralai, et ces exemples auraient échoué. Sources : OCR Processor · Document QnA.

Un point d’entrée unique

Toute l’extraction de documents passe par un seul point de terminaison : /v1/ocr, ou son équivalent dans le SDK Python, client.ocr.process(). Que tu traites la photo d’un reçu ou un rapport annuel de 800 pages, l’appel reste identique. Cette leçon détaille comment le configurer, les trois façons de lui transmettre un document et ce qu’il renvoie.

Installation et configuration

L’installation tient en une seule commande :

pip install mistralai

Ensuite, instancie le client avec ta clé API :

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

Cette approche fonctionne pour un test rapide dans un notebook, mais elle risque d’exposer ta clé par accident lors d’un commit. Dès que le code quitte ta machine, utilise une variable d’environnement :

export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral

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

Nous utiliserons cette seconde forme dans toutes les leçons suivantes.

Paramètres d’appel

L’appel client.ocr.process() ne requiert que deux paramètres : model, toujours défini sur "mistral-ocr-latest", et document, qui décrit le fichier à traiter selon l’une des trois formes détaillées ci-dessous.

D’autres paramètres ajustent la sortie selon tes 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 boîtes englobantes
  • document_annotation_format : Schéma d’annotation complet du document
  • document_annotation_prompt : Instructions de haut niveau pour l’annotation

Les deux premiers concernent l’OCR proprement dit et seront traités dans les prochaines leçons. Les trois derniers relèvent des annotations, abordées à partir de la leçon 9 ; retiens simplement pour l’instant qu’ils te permettent de demander une extraction structurée dans le même appel, sans aller-retour supplémentaire.

Trois façons d’envoyer un document

La première, via une URL publique, est la plus directe lorsque 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://example.com/document.pdf"
    }
)

La seconde est nécessaire pour les documents résidant sur ta machine ou dans un stockage privé. Tu les encodes en base64 et les envoies dans le corps de la requête. C’est la méthode par défaut pour tout contenu confidentiel, car aucune URL n’a besoin d’être exposée :

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}"
    }
)

La troisième utilise l’API Files. Tu télécharges le fichier une fois, récupères un identifiant, puis le références dans tes appels. L’avantage se manifeste avec les gros documents, ou lorsqu’un même fichier doit être traité plusieurs fois — une extraction OCR aujourd’hui, une annotation avec un schéma différent demain : tu évites de retransférer 40 Mo à chaque tentative.

# Téléchargement du fichier
uploaded_file = client.files.upload(
    file=open("my_document.pdf", "rb"),
    purpose="ocr"
)

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

Lecture de la réponse

La réponse expose une liste de pages, et chaque page porte son contenu ainsi que ses métadonnées. Une boucle minimale suffit à vérifier que l’extraction s’est bien déroulée :

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}")

Prends l’habitude d’exécuter ce type de boucle sur un document échantillon avant d’industrialiser quoi que ce soit : cela te dit en trois secondes si le nombre de pages correspond, si des images ont été détectées et si les en-têtes sont correctement isolés du corps du texte.

Limites et erreurs

Trois contraintes régissent l’usage : 50 Mo maximum par fichier, 1 000 pages par document, et les formats d’entrée PDF, PNG, JPEG, AVIF, PPTX et DOCX. S’y ajoute la limitation de débit (rate limiting), avec un seuil dépendant de ton niveau d’abonnement — un point à vérifier avant toute parallélisation massive, sous peine de voir tes appels rejetés par rafales.

Ces limites, tout comme les incidents réseau, se manifestent par des exceptions que tu dois intercepter. Un traitement par lots qui s’arrête à la facture numéro 300 parce qu’un fichier dépasse la taille autorisée constitue une perte de temps évitable :

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}")

Distinguer ces deux niveaux d’exception est utile : SDKError te fournit un code de statut sur lequel baser ta décision de réessai — un 429 doit être réessayé après un délai, jamais un 400 — tandis que le bloc générique attrape les problèmes locaux, comme un fichier manquant ou un encodage impossible.

Galvenās atziņas

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