Ir para o conteúdo principal
Português— Escolher um idioma
Menu

API de OCR da Mistral

Aula 4 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Um único ponto de entrada
  2. Instalação e configuração
  3. Parâmetros da chamada
  4. Três formas de enviar um documento
  5. Leitura da resposta
  6. Limites e erros
  7. Pontos-chave

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 alias mistral-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 tipo document_base64, encontrado em exemplos mais antigos, não existe na documentação nem no SDK mistralai, 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: True para receber imagens em base64
  • bbox_annotation_format: Esquema de anotação de caixas delimitadoras
  • document_annotation_format: Esquema de anotação de documento completo
  • document_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 modelo mistral-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