De Annotations API
Op deze pagina
Bijgewerkt op 2 november 2026 — OCR. OCR 4.0 (
mistral-ocr-4-0) is op 30 september 2026 buiten gebruik gesteld. Gebruik OCR 4.1 (mistral-ocr-4-1), dat sinds 31 augustus algemeen beschikbaar is tegen dezelfde prijs, of het aliasmistral-ocr-latest, dat sinds 16 juli daarnaar verwijst. OCR 4.1 voegt betrouwbaarheidsscores toe op blokniveau. Addendum van 3 november: Het vorige voorbeeld laspage.document_annotationop elke pagina; inmistralaiSDK 3.7.0 behoort dit veld tot het OCR-antwoord (ocr_response.document_annotation), terwijl pagina’s alleen hun inhoud en afbeeldingen bevatten; afbeeldingsannotaties leest u uitimage.image_annotation.
Meer dan alleen tekstextractie
OCR levert u ruwe tekst: getrouw en compleet, maar ongeordend. U krijgt Markdown, geen gestructureerde data. Annotaties zetten de volgende stap: ze halen gestructureerde gegevens uit uw documenten op basis van een schema dat u vooraf definieert. U beschrijft wat u zoekt, het model haalt het automatisch op, en uw applicatie ontvangt getypte velden in plaats van een muur van tekst die u met reguliere expressies moet parseren.
Twee analyse-niveaus
Document AI maakt onderscheid tussen twee soorten annotaties, afhankelijk van de schaal waarop ze opereren.
Bounding box-annotaties (bbox_annotation) richten zich op de afbeeldingen en grafieken die OCR heeft geïsoleerd. Het visiemodel verwerkt elke bounding box individueel om de inhoud te beschrijven. In een jaarverslag stelt dit mechanisme u in staat grafieken en diagrammen te beschrijven, afbeeldingen te classificeren (foto, logo, schema, grafiek) en tekstuele inhoud uit ingesloten afbeeldingen te extraheren—drie informatiepunten die standaard tekstextractie systematisch over het hoofd ziet.
Documentannotaties (document_annotation) behandelen het bestand als geheel. Het model analyseert de geëxtraheerde Markdown samen met de eerste acht afbeeldingen en retourneert vervolgens wat u hebt gevraagd: gestructureerde velden zoals een naam, datum of bedrag; het documenttype; een inhoudssamenvatting; of een antwoord op een specifieke vraag. Dit is het instrument voor bulkverwerking, dat u integreert in uw workflows voor facturen, formulieren en contracten.
Het Pydantic-schema als contract
Annotaties vertrouwen op Pydantic-modellen om de uitvoerstructuur te definiëren. Elk attribuut wordt een te extraheren veld, en de description dient als instructie voor het model: deze heeft evenveel gewicht als de veldnaam zelf.
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)")
Een volledig document annoteren
De aanroep blijft hetzelfde als bij OCR: u voegt eenvoudig de parameter document_annotation_format toe, gevuld met response_format_from_pydantic_model(), die uw model vertaalt naar een schema dat de API kan gebruiken. Bij terugkeer komt de annotatie aan als een JSON-tekenreeks, die u opnieuw valideert met Pydantic om een veilig Python-object te verkrijgen.
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
)
)
# De documentannotatie wordt door het antwoord gedragen, niet door elke pagina
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}")
Visuals één voor één beschrijven
Voor afbeeldingen is het principe identiek, maar de parameter verandert en de resultaten worden gelezen uit page.images in plaats van de pagina zelf. Let op include_image_base64=True: zonder dit verliest u de visuals die het model zojuist heeft beschreven.
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
)
# Toegang tot afbeeldingsannotaties
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}")
Niets dwingt u om tussen de twee te kiezen: bij een geïllustreerd rapport wilt u doorgaans zowel de documentmetadata als de beschrijving van de grafieken, wat een enkele aanroep dekt door beide formaten door te geven.
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
)
Extractie sturen met een prompt
Een schema beschrijft de verwachte vorm, niet de context van het document. Wanneer uw velden dubbelzinnig zijn—meerdere datums, meerdere bedragen, twee vergelijkbare secties—helpt document_annotation_prompt de twijfel op te lossen door het model de aard van het document en de prioriteiten mee te geven. Bij een Frans handelscontract maakt deze kaderstellende zin vaak het verschil tussen bruikbare extractie en een benaderende invulling.
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."
)
)
Belangrijkste punten
- Twee soorten annotaties:
bbox_annotationvoor afbeeldingen,document_annotationvoor het volledige document - Pydantic-schema’s definiëren de structuur van de te extraheren gegevens
- Gebruik
response_format_from_pydantic_model()om het schema om te zetten - De
document_annotation_promptstuurt de extractie met contextuele instructies - Beide typen kunnen in één aanroep worden gecombineerd