Ir al contenido principal
Español— Elegir un idioma
Menú

La API de OCR de Mistral

Lección 4 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Un único punto de entrada
  2. Instalación y configuración
  3. Parámetros de la llamada
  4. Tres formas de enviar un documento
  5. Lectura de la respuesta
  6. Límites y errores
  7. Puntos clave

Actualizado el 2 de noviembre de 2026 — OCR. El modelo OCR 4.0 (mistral-ocr-4-0) se retiró el 30 de septiembre de 2026. Debes utilizar OCR 4.1 (mistral-ocr-4-1), disponible para uso general desde el 31 de agosto al mismo precio, o bien el alias mistral-ocr-latest, que apunta a esta versión desde el 16 de julio. OCR 4.1 incorpora puntuaciones de confianza a nivel de bloque. Nota añadida el 3 de noviembre de 2026: Para enviar un PDF local, codifícalo en base64 como {"type": "document_url", "document_url": "data:application/pdf;base64,…"}. El tipo document_base64 que aparecía en ejemplos antiguos no existe ni en la documentación ni en el SDK mistralai; dichos ejemplos habrían fallado. Fuentes: Procesador de OCR · Preguntas y respuestas sobre documentos.

Un único punto de entrada

Toda la extracción de documentos se realiza a través de un único endpoint: /v1/ocr, o su equivalente en el SDK de Python, client.ocr.process(). Da igual si estás procesando la foto de un ticket o un informe anual de 800 páginas; la llamada es la misma. En esta lección detallaremos cómo configurarla, las tres formas de pasarle un documento y qué devuelve.

Instalación y configuración

La instalación requiere un solo comando:

pip install mistralai

A continuación, instancia el cliente con tu clave de API:

from mistralai.client import Mistral

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

Este enfoque sirve para una prueba rápida en un cuaderno, pero conlleva el riesgo de subir accidentalmente tu clave al repositorio. En cuanto el código salga de tu máquina, utiliza una variable de entorno:

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

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

Usaremos esta segunda forma en todas las lecciones siguientes.

Parámetros de la llamada

La llamada client.ocr.process() solo requiere dos parámetros: model, que siempre debe establecerse en "mistral-ocr-latest", y document, que describe el archivo a procesar en una de las tres formas que detallaremos más abajo.

Otros parámetros ajustan la salida a tus necesidades:

  • table_format: Formato de tabla (null, "markdown", "html")
  • include_image_base64: True para recibir las imágenes en base64
  • bbox_annotation_format: Esquema de anotación de cuadros delimitadores
  • document_annotation_format: Esquema de anotación de documento completo
  • document_annotation_prompt: Instrucciones de alto nivel para la anotación

Los dos primeros afectan al OCR propiamente dicho y los verás en las próximas lecciones. Los tres últimos se refieren a las anotaciones, que cubriremos a partir de la Lección 9; por ahora, basta con que recuerdes que te permiten solicitar una extracción estructurada en la misma llamada, sin necesidad de una segunda ida y vuelta.

Tres formas de enviar un documento

La primera, mediante una URL pública, es la más directa cuando el archivo ya es accesible en línea: un informe publicado o un adjunto almacenado en un bucket público.

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

La segunda es necesaria para documentos que residen en tu máquina o en un almacenamiento privado. Debes codificarlos en base64 y enviarlos en el cuerpo de la solicitud. Este es el método predeterminado para cualquier contenido confidencial, ya que no hace falta exponer ninguna 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}"
    }
)

La tercera utiliza la API de Files. Subes el archivo una vez, recuperas un ID y luego lo referencias en tus llamadas. La ventaja se hace evidente con documentos grandes o cuando hay que procesar el mismo archivo varias veces: una extracción OCR hoy, una anotación con un esquema diferente mañana; así evitas retransferir 40 MB en cada intento.

# Subir el archivo
uploaded_file = client.files.upload(
    file=open("my_document.pdf", "rb"),
    purpose="ocr"
)

# Usar el archivo subido
ocr_response = client.ocr.process(
    model="mistral-ocr-latest",
    document={
        "type": "file_id",
        "file_id": uploaded_file.id
    }
)

Lectura de la respuesta

La respuesta expone una lista de páginas, y cada página contiene su contenido junto con sus metadatos. Un bucle mínimo basta para verificar que la extracción ha ido bien:

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

Acostúmbrate a ejecutar este tipo de bucle con un documento de muestra antes de industrializar cualquier proceso: en tres segundos te dirá si el número de páginas coincide, si se han detectado imágenes y si los encabezados están correctamente aislados del cuerpo del texto.

Límites y errores

Tres restricciones rigen el uso: máximo 50 MB por archivo, 1.000 páginas por documento y formatos de entrada PDF, PNG, JPEG, AVIF, PPTX y DOCX. A esto se suma la limitación de tasa (rate limiting), con un umbral que depende de tu nivel de suscripción; es un punto que debes comprobar antes de lanzar una paralelización masiva, o te arriesgas a que rechacen tus llamadas en ráfaga.

Estos límites, al igual que los incidentes de red, se manifiestan como excepciones que debes capturar. Un trabajo por lotes que se detiene en la factura número 300 porque un archivo supera el tamaño permitido es una pérdida de tiempo evitable:

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

Distinguir entre los dos niveles de excepción resulta útil: SDKError te proporciona un código de estado con el que decidir si reintentar (un 429 debe reintentarse tras un retraso, un 400 nunca), mientras que el bloque genérico captura problemas locales, como un archivo faltante o una codificación imposible.

Puntos clave

  • El endpoint de OCR es client.ocr.process() con el modelo mistral-ocr-latest
  • Tres métodos de envío: URL pública, base64 y archivo subido
  • Los parámetros opcionales controlan el formato de tabla y la inclusión de imágenes
  • La respuesta se estructura página por página con Markdown, imágenes y metadatos
  • Respeta los límites de 50 MB y 1.000 páginas por documento