La API de anotaciones
En esta página
Actualizado el 2 de noviembre de 2026 — OCR. 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. Addenda del 3 de noviembre: El ejemplo anterior leíapage.document_annotationen cada página; en el SDKmistralai3.7.0, este campo pertenece a la respuesta OCR (ocr_response.document_annotation), mientras que las páginas contienen solo su contenido e imágenes; las anotaciones de imagen se leen desdeimage.image_annotation.
Más allá de la extracción de texto
El OCR te proporciona texto crudo: fiel y completo, pero indiferenciado. Obtienes Markdown, no datos. Las anotaciones dan el siguiente paso: extraen datos estructurados de tus documentos basándose en un esquema que defines de antemano. Describes qué estás buscando, el modelo lo extrae automáticamente y tu aplicación recibe campos tipados en lugar de un muro de texto que debas analizar con expresiones regulares.
Dos niveles de análisis
Document AI distingue entre dos tipos de anotaciones según la escala a la que operan.
Las anotaciones de cuadro delimitador (bbox_annotation) se centran en las imágenes y gráficos que el OCR ha aislado. El modelo de visión procesa cada cuadro delimitador individualmente para describir su contenido. En un informe anual, este mecanismo te permite describir gráficos y diagramas, clasificar imágenes (fotografía, logotipo, esquema, gráfica) y extraer contenido textual de imágenes incrustadas: tres piezas de información que la extracción de texto estándar pasa por alto sistemáticamente.
Las anotaciones de documento (document_annotation) tratan el archivo como un todo. El modelo analiza el Markdown extraído junto con las primeras ocho imágenes y devuelve lo que has solicitado: campos estructurados como un nombre, una fecha o un importe; el tipo de documento; un resumen del contenido; o una respuesta a una pregunta específica. Esta es la herramienta para el procesamiento por lotes, la que integrarás en tus flujos de trabajo de facturas, formularios y contratos.
El esquema Pydantic actúa como contrato
Las anotaciones dependen de modelos Pydantic para definir la estructura de salida. Cada atributo se convierte en un campo que extraer, y su description sirve como instrucción para el modelo: tiene tanto peso como el propio nombre del campo.
from pydantic import BaseModel, Field
from typing import Optional
class InvoiceExtraction(BaseModel):
vendor: str = Field(..., description="Vendor name")
invoice_number: str = Field(..., description="Invoice number")
issue_date: str = Field(..., description="Issue date (YYYY-MM-DD)")
amount_excl_tax: float = Field(..., description="Amount excluding tax")
amount_incl_tax: float = Field(..., description="Amount including tax")
currency: str = Field(default="EUR", description="Currency (ISO code)")
Anotar un documento completo
La llamada sigue siendo la misma que para el OCR: simplemente añades el parámetro document_annotation_format, poblado mediante response_format_from_pydantic_model(), que traduce tu modelo a un esquema que la API puede utilizar. Al retornar, la anotación llega como una cadena JSON, que vuelves a validar con Pydantic para obtener un objeto Python seguro.
import os
from mistralai.client import Mistral
from mistralai.extra import response_format_from_pydantic_model
from pydantic import BaseModel, Field
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
class InvoiceExtraction(BaseModel):
vendor: str = Field(..., description="Vendor name")
invoice_number: str = Field(..., description="Invoice number")
issue_date: str = Field(..., description="Issue date (YYYY-MM-DD)")
amount_excl_tax: float = Field(..., description="Amount excluding tax")
amount_incl_tax: float = Field(..., description="Amount including tax")
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/invoice.pdf"
},
document_annotation_format=response_format_from_pydantic_model(
InvoiceExtraction
)
)
# La anotación del documento la lleva la respuesta, no cada página
if ocr_response.document_annotation:
invoice = InvoiceExtraction.model_validate_json(
ocr_response.document_annotation
)
print(f"Vendor: {invoice.vendor}")
print(f"Amount incl. tax: {invoice.amount_incl_tax}")
Describir elementos visuales uno a uno
Para las imágenes, el principio es idéntico pero el parámetro cambia, y los resultados se leen desde page.images en lugar de desde la página en sí. Ten en cuenta include_image_base64=True: sin ello, pierdes los elementos visuales que el modelo acaba de describir.
from pydantic import BaseModel, Field
from mistralai.extra import response_format_from_pydantic_model
class ImageDescription(BaseModel):
image_type: str = Field(
..., description="Type: graph, table, photo, logo, schematic"
)
description: str = Field(
..., description="Short description of the image in English"
)
relevant_content: str = Field(
..., description="Summary of the informative content of the image"
)
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/report.pdf"
},
bbox_annotation_format=response_format_from_pydantic_model(
ImageDescription
),
include_image_base64=True
)
# Acceso a las anotaciones de imagen
for page in ocr_response.pages:
for image in page.images:
if image.image_annotation:
desc = ImageDescription.model_validate_json(image.image_annotation)
print(f"Image {image.id}: {desc.image_type}")
print(f" Description: {desc.description}")
Nada te obliga a elegir entre ambas opciones: en un informe ilustrado, generalmente querrás tanto los metadatos del documento como la descripción de sus gráficos, algo que una única llamada cubre pasando ambos formatos.
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/report.pdf"
},
bbox_annotation_format=response_format_from_pydantic_model(
ImageDescription
),
document_annotation_format=response_format_from_pydantic_model(
InvoiceExtraction
),
include_image_base64=True
)
Guiar la extracción con un prompt
Un esquema describe la forma esperada, no el contexto del documento. Cuando tus campos son ambiguos —múltiples fechas, múltiples importes, dos secciones similares—, document_annotation_prompt ayuda a resolver la duda indicando al modelo la naturaleza del documento y qué debe priorizar. En un contrato mercantil francés, esta frase de encuadre suele marcar la diferencia entre una extracción usable y un relleno aproximado.
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/contract.pdf"
},
document_annotation_format=response_format_from_pydantic_model(
ContractExtraction
),
document_annotation_prompt=(
"This document is a French commercial contract. "
"Extract information about the contracting parties, "
"the contract duration, and the main clauses."
)
)
Puntos clave
- Dos tipos de anotaciones:
bbox_annotationpara imágenes,document_annotationpara todo el documento - Los esquemas Pydantic definen la estructura de los datos a extraer
- Usa
response_format_from_pydantic_model()para convertir el esquema - El
document_annotation_promptguía la extracción con instrucciones contextuales - Ambos tipos pueden combinarse en una única llamada