API de OCR da Mistral
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: Para enviar um PDF local, codifique-o em base64 como{"type": "document_url", "document_url": "data:application/pdf;base64,…"}. O tipodocument_base64, encontrado em exemplos mais antigos, não existe na documentação nem no SDKmistralai, e esses exemplos teriam falhado. Fontes: Processador de OCR · Documento QnA.
Um único ponto de entrada
Toda a extração de documentos passa por um único endpoint: /v1/ocr, ou o seu equivalente no SDK Python, client.ocr.process(). Quer esteja a processar a fotografia de um recibo ou um relatório anual de 800 páginas, a chamada é a mesma. Esta lição detalha como configurá-la, as três formas de lhe passar um documento e o que ela devolve.
Instalação e configuração
A instalação requer apenas um comando:
pip install mistralai
De seguida, instancie o cliente com a sua chave de API:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
Esta abordagem funciona para um teste rápido num notebook, mas corre o risco de comprometer acidentalmente a sua chave. Assim que o código sair da sua máquina, utilize uma variável de ambiente:
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Utilizaremos esta segunda forma em todas as lições subsequentes.
Parâmetros da chamada
A chamada client.ocr.process() requer apenas dois parâmetros: model, sempre definido como "mistral-ocr-latest", e document, que descreve o ficheiro a processar numa das três formas detalhadas abaixo.
Outros parâmetros ajustam o resultado às suas necessidades:
table_format: Formato da tabela (null,"markdown","html")include_image_base64:Truepara receber imagens em base64bbox_annotation_format: Esquema de anotação de caixas delimitadorasdocument_annotation_format: Esquema de anotação de documento completodocument_annotation_prompt: Instruções de alto nível para anotação
Os dois primeiros dizem respeito ao próprio OCR e serão tratados nas próximas lições. Os últimos três relacionam-se com anotações, abordadas a partir da Lição 9; por agora, lembre-se apenas de que permitem solicitar uma extração estruturada na mesma chamada, sem uma segunda ida e volta à rede.
Três formas de enviar um documento
A primeira, um URL público, é a mais direta quando o ficheiro já está acessível online — um relatório publicado, um anexo armazenado num bucket público:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
A segunda é necessária para documentos que residem na sua máquina ou em armazenamento privado. Codifica-os em base64 e envia-os no corpo do pedido. Este é o método padrão para qualquer coisa confidencial, uma vez que não é necessário expor nenhum URL:
import base64
with open("my_document.pdf", "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}"
}
)
A terceira utiliza a API de Ficheiros. Carrega o ficheiro uma vez, recupera um ID e, em seguida, referencia-o nas suas chamadas. O benefício manifesta-se com documentos grandes ou quando o mesmo ficheiro deve ser processado várias vezes — uma extração de OCR hoje, uma anotação com um esquema diferente amanhã: não volta a transferir 40 MB em cada tentativa.
# Carregar o ficheiro
uploaded_file = client.files.upload(
file=open("my_document.pdf", "rb"),
purpose="ocr"
)
# Utilizar o ficheiro carregado
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "file_id",
"file_id": uploaded_file.id
}
)
Leitura da resposta
A resposta expõe uma lista de páginas e cada página transporta o seu conteúdo juntamente com os seus metadados. Um ciclo mínimo é suficiente para verificar se a extração correu bem:
for page in ocr_response.pages:
print(f"Page {page.index}")
print(f"Content: {page.markdown[:200]}...")
print(f"Images: {len(page.images)} found")
print(f"Header: {page.header}")
print(f"Footer: {page.footer}")
print(f"Dimensions: {page.dimensions}")
Crie o hábito de executar este tipo de ciclo num documento de amostra antes de industrializar qualquer coisa: diz-lhe em três segundos se a contagem de páginas corresponde, se as imagens foram detetadas e se os cabeçalhos estão devidamente isolados do corpo do texto.
Limites e erros
Três restrições governam a utilização: máximo de 50 MB por ficheiro, 1.000 páginas por documento e formatos de entrada PDF, PNG, JPEG, AVIF, PPTX e DOCX. A isto soma-se a limitação de taxa (rate limiting), com um limiar que depende do seu nível de subscrição — um ponto a verificar antes de uma paralelização massiva, sob risco de ver as suas chamadas rejeitadas em rajada.
Estes limites, tal como incidentes de rede, manifestam-se como exceções que deve capturar. Um trabalho em lote que para na fatura número 300 porque um ficheiro excede o tamanho permitido é um desperdício de tempo evitável:
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
try:
ocr_response = client.ocr.process(
model="mistral-ocr-latest",
document={
"type": "document_url",
"document_url": "https://example.com/document.pdf"
}
)
except SDKError as e:
print(f"API Error: {e.status_code} - {e.message}")
except Exception as e:
print(f"Unexpected error: {e}")
Distinguir os dois níveis de exceção é útil: SDKError fornece-lhe um código de estado com base no qual decidir se deve repetir a tentativa — um 429 deve ser repetido após um atraso, um 400 nunca — enquanto o bloco genérico captura problemas locais, como um ficheiro em falta ou uma codificação impossível.
Pontos-chave
- O endpoint de OCR é
client.ocr.process()com o modelomistral-ocr-latest - Três métodos de envio: URL público, base64, ficheiro carregado
- Parâmetros opcionais controlam o formato da tabela e a inclusão de imagens
- A resposta é estruturada página a página com Markdown, imagens e metadados
- Respeite os limites de 50 MB e 1.000 páginas por documento