Skip to content
AI Tools

Mistral OCR 4.1 Tutorial: Blocks That Actually Work

Mistral OCR 4.1 shipped with tighter boxes and block confidence. Here's the faster API path vs Document AI, plus code you can run today.

6 min readBeginner

Key takeaway: For most pipelines, plain Mistral OCR 4.1 with include_blocks=True and block-level confidence beats Document AI schema annotations. You get structure you can gate and chunk, without the higher annotated-page bill.

Same /v1/ocr endpoint. Alias mistral-ocr-latest already points at 4.1 (as of the July 2026 public preview). Tighter paragraph boxes, structural labels, confidence you can filter on. This walkthrough is production-shaped, not a feature laundry list.

Two ways people hit Mistral OCR 4.1

Two patterns show up in real codebases. Day-one extraction? They’re not equal.

Approach What you get Bill (as of mid-2026) Best when
A. Raw OCR + blocks Markdown, paragraph bboxes, block types, optional confidence $4 / 1,000 pages ($2 batch) RAG chunking, audit highlights, human review queues
B. Document AI annotations Same OCR plus schema-shaped JSON (extra model pass) $5 / 1,000 annotated pages Fixed forms where you already own a JSON schema

Method A wins for general documents. Full control of structure. No full-document annotation ceiling eating your long PDFs. Plain OCR is $4/1k pages and annotated pages are $5/1k on Mistral’s OCR 4.1 model card; the OCR 4 launch post (June 23, 2026) also notes a 50% Batch cut on the OCR path → $2/1k.

What actually changed in 4.1

OCR 4 (June 2026) already shipped boxes, block types, and confidence. 4.1 is polish. Team list from the release notes: boxes align without nested-image drift. Reference lists keep one box per citation. Fewer missed blocks on busy pages. Double quotes stay double. More checkbox styles. Better right-to-left tables.

If you’ve ever watched a “perfect” markdown dump quietly invent a sentence that was never on the scan, you already know why labeled blocks plus scores matter more than another leaderboard screenshot.

Method A walkthrough: blocks + confidence gates

Install the official client, set MISTRAL_API_KEY, call client.ocr.process. Parameter reference sits in the OCR processor guide.

import os
from mistralai.client import Mistral

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

resp = client.ocr.process(
 model="mistral-ocr-4-1", # pin in prod; latest aliases to 4.1 as of the 4.1 release
 document={
 "type": "document_url",
 "document_url": "https://YOUR_PUBLIC_HOST/sample-scan.pdf", # must be reachable by Mistral
 },
 include_blocks=True,
 confidence_scores_granularity="block",
 table_format="html",
 extract_header=True,
 extract_footer=True,
)

for page in resp.pages:
 print("page", page.index, "md chars", len(page.markdown or ""))
 for b in page.blocks or []:
 scores = getattr(b, "confidence_scores", None) or {}
 avg = scores.get("average_content_confidence_score")
 # drop weak text-like blocks before they hit your index
 if b.type in {"text", "title", "list"} and avg is not None and avg < 0.85:
 continue
 print(b.type, b.content[:120] if b.content else "")

Each block carries type, bbox corners (top_left_x/y, bottom_right_x/y), and content in reading order. Granularity "block" adds average/min content confidence plus a block-type confidence. Image-only blocks can return null content scores – that’s expected, not a bug.

Funny thing about confidence gates: the first PDF you try will either look clean at 0.9+ or dump a cluster of 0.6 junk around stamps and faded stamps. That first histogram is more honest than any benchmark table.

Pro tip: Pin mistral-ocr-4-1 (or keep OCR 3 on purpose at $2/1k). mistral-ocr-latest already routes to 4.1 – quiet alias bumps are how page bills double overnight. OCR 3 stays on the old $2 rate if you call that generation explicitly.

Useful labels from the docs: text, title, list, table, image, equation, caption, code, references, aside_text, header, footer, signature. For RAG, chunk on title/text/list and keep the bbox so citations can highlight the source region later. include_blocks only fills on OCR 4+; older model ids accept the param and return an empty array.

When Method B still wins

Fixed form. Twelve fields. You already own the JSON schema. Pass it through document annotation params – same OCR engine underneath, extra structured pass on top. Cost moves to the annotated rate ($5/1k as of the model card).

The catch is length. Official cookbooks cap full-document annotations at 8 pages per call. Split longer PDFs or the request fails/partial-extracts. Bbox-level image annotations don’t share that 8-page rule, which is why Method A stays the default spine and B stays a specialist layer.

Edge cases that bite after the demo

  • Confidence is off unless you ask. Leave confidence_scores_granularity unset and you get a smaller payload – with nothing to gate on.
  • Headers/footers bleed into markdown unless you set extract_header / extract_footer. Want clean body text? Turn them on.
  • URLs must be public to Mistral.document_url / image_url need a path their servers can fetch. Private buckets: signed URL, base64, or Files API (uploads up to 512 MB per known limits; files retained 30 days).
  • Hallucination risk isn’t zero. HN users described OCR 4.0 inventing full sentences mid-page. 4.1’s public notes cover layout, checkboxes, and RTL – not a written “no more invented prose” promise. Low block scores + spot checks still matter on legal or archival scans.
  • Batch tradeoffs. Batch drops OCR to $2/1k and skips realtime rate limits, but jobs are async and results stay downloadable only 24 hours after completion (platform limits docs).

Want a no-code sniff test first? Drop one messy page in the Studio OCR playground.

FAQ

Is Mistral OCR 4.1 free?

No. As of the current model card: $4 per 1,000 OCR pages, $5 per 1,000 annotated pages. Batch plain OCR: $2 per 1,000.

Do I need include_blocks every time?

Only when location or labels matter. Quick markdown into a notes app? Skip it. RAG, redaction, or source highlights? Turn it on – blocks are why OCR 4 was worth the jump. Debugging empty blocks on a pre-OCR-4 model id wastes an afternoon; the param is accepted and returns [].

Should I use a general VLM instead of Mistral OCR 4.1?

Bulk ingestion: dedicated OCR stays cheaper and more predictable per page, with native block types and no prompt coaxing. Weird handwriting or “explain this figure” one-offs: a general VLM can win. Common hybrid from community threads – Mistral first, second model only on low-confidence pages. Remember that 0.85 gate in the snippet? That’s the branch point.

Grab an API key, run the snippet on your messiest scan, and log how many blocks fall under 0.85 average confidence. That single count tells you bulk-index vs human queue – faster than another benchmark chart.

Related Tutorials