Tu primera llamada OCR en Python
En esta página
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. Utiliza OCR 4.1 (mistral-ocr-4-1), disponible de forma general desde el 31 de agosto al mismo precio, o el aliasmistral-ocr-latest, que apunta a él desde el 16 de julio. OCR 4.1 añade puntuaciones de confianza a nivel de bloque. Addendum del 3 de noviembre de 2026: Un PDF local se transmite en base64 como{"type": "document_url", "document_url": "data:application/pdf;base64,…"}; el tipodocument_base64de ejemplos anteriores no existe ni en la documentación ni en el SDKmistralai, y esos ejemplos habrían fallado. Fuentes: Procesador OCR · Preguntas y respuestas sobre documentos.
De la teoría al código
Ya conoces el punto de acceso (endpoint) y sus parámetros. Es hora de escribir un script completo que extraiga texto de un PDF, desde la primera línea de importación hasta el archivo Markdown guardado en tu disco. Empezaremos con el caso más sencillo —un documento público— y luego pasaremos a lo que te encontrarás en la práctica: archivos locales, imágenes aisladas y documentos ilustrados que necesitan reconstrucción.
Dos prerrequisitos, ya cubiertos pero que vale la pena verificar antes de perder diez minutos con un error de autenticación:
pip install mistralai
export MISTRAL_API_KEY="tu-clave-api"
El script mínimo
Aquí tienes la extracción completa de un PDF accesible en línea. Tres líneas útiles: instanciar el cliente, llamar a process e iterar sobre las páginas.
import os
from mistralai.client import Mistral
# Inicializar el cliente
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Llamada OCR sobre un PDF público
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://arxiv.org/pdf/2201.04234"
}
)
# Mostrar el número de páginas
print(f"Número de páginas: {len(ocr_response.pages)}")
# Mostrar el contenido de cada página
for page in ocr_response.pages:
print(f"\n--- Página {page.index + 1} ---")
print(page.markdown)
Observa el page.index + 1: el índice devuelto por la API empieza en cero, mientras que tus usuarios cuentan desde uno. Es un desfase menor mientras lo tengas presente, pero una fuente de confusión duradera cuando lo descubres en un informe entregado a un cliente.
Procesar un archivo desde tu máquina
En la vida real, los documentos rara vez llegan mediante una URL pública. Los tienes en el disco, son confidenciales, así que los codificas en base64. El siguiente script procesa una factura de proveedor y concatena todas las páginas en un único bloque de texto:
import os
import base64
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Leer y codificar el archivo local
file_path = "factura_proveedor.pdf"
with open(file_path, "rb") as f:
document_base64 = base64.b64encode(f.read()).decode("utf-8")
# Llamada OCR
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": f"data:application/pdf;base64,{document_base64}"
}
)
# Concatenar todo el texto
full_text = "\n\n".join(
page.markdown for page in ocr_response.pages
)
print(full_text)
La concatenación mediante "\n\n".join(...) funciona bien para la visualización o la búsqueda de texto completo. Sin embargo, borra el límite entre páginas: si más adelante necesitas citar una fuente o dirigir a un usuario a la página correcta de un contrato, conserva la estructura página por página en lugar de este único bloque.
Guardar la extracción
Cada llamada OCR cuesta dinero y lleva tiempo. Volver a ejecutar la extracción del mismo informe de doscientas páginas porque olvidaste guardar el resultado es un error que solo se comete una vez. La función siguiente escribe el Markdown en un archivo, marcando los saltos de página con un comentario y un separador:
import os
import base64
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
def extract_pdf(pdf_path: str, output_path: str) -> None:
"""Extrae texto de un PDF y lo guarda como Markdown."""
with open(pdf_path, "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}"
}
)
with open(output_path, "w", encoding="utf-8") as f:
for page in ocr_response.pages:
f.write(f"<!-- Página {page.index + 1} -->\n\n")
f.write(page.markdown)
f.write("\n\n---\n\n")
print(f"Extracción completada: {len(ocr_response.pages)} páginas")
print(f"Resultado guardado en: {output_path}")
# Uso
extract_pdf("informe_anual.pdf", "informe_anual.md")
El comentario HTML <!-- Página N --> es invisible en la vista renderizada pero permanece presente en el archivo: puedes encontrarlo mediante expresiones regulares para reconstruir la paginación durante la indexación.
El caso de una imagen aislada
OCR 4 no se limita a los PDF. Una foto de una factura tomada con el móvil, un recibo escaneado, una captura de pantalla; todo se envía de la misma manera, utilizando el tipo image_base64:
import os
import base64
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Codificar una imagen
with open("factura_escaneada.png", "rb") as f:
image_base64 = base64.b64encode(f.read()).decode("utf-8")
# Llamada OCR sobre una imagen
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "image_base64",
"image_base64": image_base64
}
)
# Una única "página" para una imagen
print(ocr_response.pages[0].markdown)
La respuesta mantiene la misma forma: una lista de páginas, que en este caso contiene solo una. Por tanto, tu código de procesamiento permanece idéntico independientemente del tipo de archivo de entrada, lo cual simplifica enormemente las canalizaciones (pipelines) mixtas.
Reconstruir un documento ilustrado
El Markdown devuelto hace referencia a las imágenes como , sin incrustarlas. Si deseas un archivo independiente —un informe legible sin conexión, una vista previa para enviar por correo electrónico—, solicita las imágenes en base64 y reemplaza cada referencia con un URI de datos:
import os
import base64
import re
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://arxiv.org/pdf/2201.04234"
},
include_image_base64=True
)
for page in ocr_response.pages:
markdown = page.markdown
# Reemplazar referencias de imágenes con base64
for image in page.images:
placeholder = f""
data_uri = f""
markdown = markdown.replace(placeholder, data_uri)
print(markdown[:500])
El archivo resultante crece rápidamente, ya que el base64 pesa aproximadamente un tercio más que el binario original. Reserva esta reconstrucción para los documentos que necesites hacer independientes y mantén las imágenes como archivos separados en tus canalizaciones de indexación.
Antes de continuar, toma un documento propio —una factura, un contrato, una página escaneada— y ejecútalo a través del script de extracción local. Compara el Markdown resultante con el original línea por línea: las discrepancias que encuentres, una tabla mal reconstruida o un encabezado absorbido por el cuerpo del texto, son exactamente los problemas que las próximas tres lecciones te enseñarán a gestionar.
Puntos clave
- La llamada OCR requiere 3 líneas: cliente, proceso, leer páginas
- Usa base64 para archivos locales y URL para documentos públicos
- El resultado es Markdown estructurado, listo para usar
- Las imágenes extraídas pueden recombinarse con el texto
- Guarda siempre tus extracciones para evitar llamadas repetidas a la API