A Sua Primeira Chamada OCR em Python
Nesta página
Atualizado em 2 de novembro de 2026 — OCR. O OCR 4.0 (
mistral-ocr-4-0) foi desativado a 30 de setembro de 2026. Utilize o OCR 4.1 (mistral-ocr-4-1), disponível para uso geral desde 31 de agosto pelo mesmo preço, ou o aliasmistral-ocr-latest, que aponta para esta versão desde 16 de julho. O OCR 4.1 adiciona pontuações de confiança ao nível do bloco. Adenda de 3 de novembro de 2026: Um PDF local é transmitido em base64 como{"type": "document_url", "document_url": "data:application/pdf;base64,…"}; o tipodocument_base64de exemplos anteriores não existe nem na documentação nem no SDKmistralai, e esses exemplos teriam falhado. Fontes: OCR Processor · Document QnA.
Da Teoria ao Código
Já conhece o endpoint e os seus parâmetros. É altura de escrever um script completo que extraia texto de um PDF, desde a primeira linha de importação até ao ficheiro Markdown guardado no seu disco. Começaremos pelo caso mais simples — um documento público — e avançaremos depois para o que encontrará na prática: ficheiros locais, imagens isoladas e documentos ilustrados que necessitam de reconstrução.
Dois pré-requisitos, já abordados, mas que vale a pena verificar antes de perder dez minutos com um erro de autenticação:
pip install mistralai
export MISTRAL_API_KEY="your-api-key"
O Script Mínimo
Eis a extração completa de um PDF acessível online. Três linhas úteis: instanciar o cliente, chamar process e iterar sobre as páginas.
import os
from mistralai.client import Mistral
# Initialize the client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# OCR call on a public PDF
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://arxiv.org/pdf/2201.04234"
}
)
# Display the number of pages
print(f"Number of pages: {len(ocr_response.pages)}")
# Display the content of each page
for page in ocr_response.pages:
print(f"\n--- Page {page.index + 1} ---")
print(page.markdown)
Note o page.index + 1: o índice devolvido pela API começa em zero, enquanto os seus utilizadores contam a partir de um. É um desvio menor, desde que o tenha em mente, mas uma fonte de confusão duradoura quando o descobre num relatório entregue a um cliente.
Processamento de um Ficheiro do Seu Computador
Na vida real, os documentos raramente chegam através de um URL público. Tem-nos no seu disco, são confidenciais, pelo que os codifica em base64. O script seguinte processa uma fatura de fornecedor e concatena todas as páginas num único bloco de texto:
import os
import base64
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Read and encode the local file
file_path = "supplier_invoice.pdf"
with open(file_path, "rb") as f:
document_base64 = base64.b64encode(f.read()).decode("utf-8")
# OCR call
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": f"data:application/pdf;base64,{document_base64}"
}
)
# Concatenate all text
full_text = "\n\n".join(
page.markdown for page in ocr_response.pages
)
print(full_text)
A concatenação via "\n\n".join(...) funciona bem para visualização ou pesquisa de texto integral. No entanto, apaga a fronteira entre páginas: se mais tarde precisar de citar uma fonte ou direcionar um utilizador para a página correta de um contrato, preserve a estrutura página a página em vez deste bloco único.
Guardar a Extração
Cada chamada OCR custa dinheiro e demora tempo. Voltar a executar a extração do mesmo relatório de duzentas páginas porque se esqueceu de guardar o resultado é um erro que só se comete uma vez. A função abaixo escreve o Markdown num ficheiro, marcando as quebras de página com um comentário e um 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:
"""Extracts text from a PDF and saves it as 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"<!-- Page {page.index + 1} -->\n\n")
f.write(page.markdown)
f.write("\n\n---\n\n")
print(f"Extraction complete: {len(ocr_response.pages)} pages")
print(f"Result saved to: {output_path}")
# Usage
extract_pdf("annual_report.pdf", "annual_report.md")
O comentário HTML <!-- Page N --> é invisível na vista renderizada, mas permanece presente no ficheiro: pode encontrá-lo via expressão regular para reconstruir a paginação durante a indexação.
O Caso de uma Imagem Isolada
O OCR 4 não se limita a PDFs. Uma fotografia de uma fatura tirada com um telemóvel, um recibo digitalizado, uma captura de ecrã — tudo é enviado da mesma forma, utilizando o tipo image_base64:
import os
import base64
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Encode an image
with open("scanned_invoice.png", "rb") as f:
image_base64 = base64.b64encode(f.read()).decode("utf-8")
# OCR call on an image
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "image_base64",
"image_base64": image_base64
}
)
# A single "page" for an image
print(ocr_response.pages[0].markdown)
A resposta mantém a mesma forma: uma lista de páginas, que neste caso contém apenas uma. O seu código de processamento permanece, portanto, idêntico independentemente do tipo de ficheiro de entrada, o que simplifica bastante os pipelines mistos.
Reconstruir um Documento Ilustrado
O Markdown devolvido referencia imagens como , sem as incorporar. Se quiser um ficheiro autónomo — um relatório legível offline, uma pré-visualização para enviar por e-mail — solicite as imagens em base64 e substitua cada referência por um URI de dados:
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
# Replace image references with base64
for image in page.images:
placeholder = f""
data_uri = f""
markdown = markdown.replace(placeholder, data_uri)
print(markdown[:500])
O ficheiro resultante cresce rapidamente, uma vez que o base64 pesa cerca de um terço a mais do que o binário original. Reserve esta reconstrução para documentos que necessite de tornar autónomos e mantenha as imagens como ficheiros separados nos seus pipelines de indexação.
Antes de avançar, pegue num documento que possua — uma fatura, um contrato, uma página digitalizada — e execute-o através do script de extração local. Compare o Markdown resultante com o original, linha por linha: as discrepâncias que encontrar, uma tabela mal reconstruída ou um cabeçalho absorvido pelo corpo do texto, são exatamente os problemas que as próximas três lições lhe ensinarão a tratar.
Pontos-chave
- A chamada OCR leva 3 linhas: cliente, process, ler páginas
- Utilize base64 para ficheiros locais, URL para documentos públicos
- O resultado é Markdown estruturado, pronto a usar
- As imagens extraídas podem ser recombinadas com o texto
- Guarde sempre as suas extrações para evitar chamadas API repetidas