PDFs no Claude Code: conversão, tokens e preservação da estrutura

O que acontece a um PDF no Claude e porque custa cada página 1 500–3 000 tokens?#

A documentação oficial da Anthropic descreve o processo em três passos simples:

Parece lógico, mas os custos de processamento aumentam linearmente com o número de páginas. E este valor explica porque é que o limite da sua subscrição se esgota com um único PDF:

Para perceber a dimensão do consumo, a Anthropic mediu o mesmo PDF de 3 páginas no Bedrock em dois modos. No modo de texto (Converse Document Chat), utilizou cerca de 1 000 tokens. Com análise visual (Claude PDF Chat), utilizou cerca de 7 000 tokens. Incluir imagens torna o processamento 7 vezes mais caro.

As capturas de ecrã das páginas são ainda piores. Uma captura de ecrã de 1000×1000 píxeis custa cerca de 1 300 tokens.

O mecanismo é simples: os PDFs são dispendiosos porque o Claude não confia no seu OCR. Usa tanto o texto como a imagem para os comparar — e paga pelas duas camadas ao mesmo tempo. Para documentos grandes, pode fazer de outra forma: guardar o ficheiro como Markdown na pasta do projeto e dizer ao Claude: «aqui está um documento com informação — distribui-a». Ele distribuirá o conteúdo pelos seus próprios ficheiros e continuará a trabalhar com o texto organizado, em vez de consumir tudo de uma só vez.

Quanto consome um PDF numa tarefa típica?#

Os valores específicos (modelo Sonnet 4.x, entrada a 3 $ por milhão de tokens):

E isto é apenas um ciclo de 4 pedidos. Depois, entra em ação a colocação de prompts em cache (TTL predefinido de 5 minutos, até 1 hora num nível alargado e até 90% de desconto em chamadas repetidas durante esse período) — as poupanças multiplicam-se.

Sempre que carrega o mesmo PDF numa conversa nova, o Claude volta a lê-lo; a cache não transita entre conversas.

Se converter uma vez o mesmo PDF de 15 páginas em Markdown e o introduzir como .md em cada um de quatro chats novos, o exemplo usa 15 × 300 × 4 = 18 000 tokens de entrada em vez de 135 000. Os 300 tokens por página convertida e 2 250 por página PDF são pressupostos do cálculo, não constantes medidas para todos os PDFs. Conte o documento real e confirme a qualidade da conversão antes de estimar poupanças.

Estas contas tornam-se ainda mais relevantes com uma subscrição Claude Pro. Um relatório de 100 páginas pode consumir todo o limite de 5 horas. Depois de o converter para Markdown, cabem mais de 10 documentos deste tipo no mesmo orçamento.

Quais são os limites da API da Anthropic para PDFs em 2026?#

A documentação da Anthropic apresenta os limites no início (atuais a 31 de maio de 2026):

O Claude.ai (a aplicação web para consumidores) tem limites diferentes: um máximo de 500 MB por ficheiro e até 20 ficheiros numa conversa. No entanto, a análise visual só funciona com PDFs até 100 páginas — acima desse limite, o Claude vê apenas texto, sem gráficos nem diagramas.

Três formas de enviar um PDF através da API:

1. Por URL - "source": {"type": "url", "url": "..."} - a opção mais simples quando o documento está online.
2. Em Base64 - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - para ficheiros locais.
3. Através da Files API - "source": {"type": "file", "file_id": "file_abc123"} - para pedidos repetidos; requer o cabeçalho beta anthropic-beta: files-api-2025-04-14.

A Files API é a principal forma de poupar ao trabalhar com o mesmo PDF em conversas diferentes. Carregue-o uma vez, obtenha um file_id e, depois, todas as interações utilizam esse identificador. Com cache_control: ephemeral, os pedidos repetidos custam 10% do preço normal.

A Anthropic também oferece recomendações oficiais para minimizar a utilização:

Método 1: Como configurar o MarkItDown em 5 minutos?#

O MarkItDown é um projeto oficial da Microsoft mantido pela equipa AutoGen. No GitHub, tem 134 mil estrelas e 9,2 mil forks (no final de maio de 2026). O seu objetivo é indicado diretamente no README:

Formatos suportados:

• Documentos: PDF, DOCX, PPTX, XLSX
• Web: HTML, JSON, XML, CSV
• Multimédia: áudio com transcrição, imagens com EXIF e OCR, vídeos do YouTube (através de legendas)
• Arquivos: ZIP, EPub
• Outros: todos os anexos de ficheiros Outlook MSG

Instalação

Requisito: Python 3.10+ (normalmente já está instalado no macOS; no Windows, tem de o instalar separadamente).

pip install 'markitdown[all]'

Se não precisar de todos os formatos, pode instalar apenas alguns:

pip install 'markitdown[pdf, docx, pptx]'

Converter um único ficheiro

O caso mais simples:

markitdown document.pdf > document.md

Depois disso, o ficheiro document.md aparecerá na pasta atual. Adicione-o ao Claude Code com @document.md ou coloque-o simplesmente junto ao projeto.

API Python

Se quiser integrar o programa no seu script:

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("research-paper.pdf")
print(result.text_content)

# Pode guardá-lo diretamente:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

O que o MarkItDown NÃO consegue fazer

• OCR de PDFs digitalizados - não devolve nada. Os documentos digitalizados requerem PyMuPDF4LLM ou Docling.
• Esquemas complexos com várias colunas - pode baralhar a ordem de leitura.
• URLs incorporados em PDFs - não os preserva.

Para PDFs simples (relatórios, artigos, documentação), o MarkItDown é a melhor opção: uma ferramenta versátil que se instala num minuto e não requer conhecimentos de Python. As medições do seu desempenho com documentos que contêm texto cirílico e documentos digitalizados estão no artigo sobre como converter um PDF em texto para IA.

Método 2: O que oferece o PyMuPDF4LLM e quando é melhor?#

O MarkItDown oferece uma grande variedade de formatos; o PyMuPDF4LLM oferece um processamento de PDF mais aprofundado.

A versão a 31 de maio de 2026 é a 1.27.2.3 (lançada a 24 de abril de 2026).

O que inclui

• Páginas com várias colunas na ordem de leitura correta
• Tabelas convertidas para Markdown com formatação GitHub
• Remoção automática de cabeçalhos e rodapés
• Imagens extraídas com ligações relativas para uma pasta separada
• OCR inteligente: aplicado apenas a zonas ilegíveis, poupando cerca de 50% do tempo de processamento
• Motor nativo em C, sem necessidade de GPU

Instalação

pip install pymupdf4llm

Utilização

import pymupdf4llm

# Utilização básica - diretamente para Markdown:
md_text = pymupdf4llm.to_markdown("document.pdf")

# Guardar:
with open("document.md", "w") as f:
    f.write(md_text)

Numa só linha, como prometido:

python3 -c "import pymupdf4llm; \
  open('document.md','w').write(pymupdf4llm.to_markdown('document.pdf'))"

Quando escolher o PyMuPDF4LLM em vez do MarkItDown

• Quando o PDF tiver muitas ligações que precisa de preservar (o MarkItDown perde-as).
• Quando o documento for digitalizado e precisar de OCR.
• Quando precisar de velocidade para processar milhares de ficheiros localmente — o motor nativo em C é mais rápido do que os wrappers Python.
• Quando precisar das imagens do PDF numa pasta separada para processamento posterior.

Detalhes da licença (importante para empresas)

O PyMuPDF4LLM tem licenciamento duplo: AGPL v3 OU licença comercial da Artifex.

AGPL significa: se utilizar a biblioteca num serviço SaaS público, tem de publicar todo o código-fonte do serviço ao abrigo da mesma licença AGPL. Para utilização interna (o seu script no portátil), não há restrições.

Para desenvolvimento comercial sem divulgar o código, compre uma licença à Artifex (artifex.com). Os preços não são publicados; solicite-os à equipa comercial.

Se estiver a desenvolver um produto para clientes, verifique a licença desde o início. O MarkItDown (MIT) e o Docling (MIT) são opções mais seguras para SaaS.

Método 3: como ligar MarkItDown a um agente de inteligência artificial no Claude Code?#

O MarkItDown no modo CLI significa «converto ficheiros manualmente com antecedência»; o servidor MCP significa «o Claude Code decide quando converter».

Instalação

Precisa do gestor de pacotes uv. Não é necessário instalar o servidor separadamente; o uv descarrega-o na primeira execução.

Configuração no Claude Code

Um único comando liga o servidor a todos os seus projetos, com a versão fixada:

claude mcp add --scope user --env 'ORT_DISABLE_TELEMETRY=1' --env 'UV_PYTHON=3.12' --transport stdio markitdown -- uvx markitdown-mcp@0.0.1a7
claude mcp list

A entrada markitdown deverá indicar «Connected». A primeira execução descarrega cerca de setenta pacotes e demora até um minuto; depois disso, o servidor inicia-se num ou dois segundos.

Eis por que motivo o comando precisa destas duas variáveis. ORT_DISABLE_TELEMETRY=1 desativa as estatísticas que o motor onnxruntime integrado no servidor envia por predefinição à Microsoft no Mac e no Linux. UV_PYTHON=3.12 executa o servidor com Python 3.12, para o qual existem pacotes pré-compilados no Windows, Linux e Macs com Apple Silicon. Nos Macs Intel e no macOS 13 e versões anteriores, o servidor não se instala com Python 3.14. Há uma ressalva para Intel e 3.12: o uv compila a biblioteca cryptography a partir do código-fonte, porque não está disponível nenhum pacote pré-compilado para Intel desde junho de 2026. A instalação demora mais tempo e pode falhar. Se não tiver Python 3.12, o uv descarrega-o por si.

O servidor é executado diretamente no seu computador e pode abrir qualquer ficheiro a que tenha acesso. Se o Claude Code estiver aberto, reinicie-o; o markitdown aparecerá na lista de servidores MCP.

Como utilizar

No Claude Code, basta dizer:

Convert /Users/your-user/Documents/report.pdf to Markdown and analyze the main points.

O Claude chama convert_to_markdown(uri) por iniciativa própria, obtém o Markdown e trabalha com ele — o PDF nem sequer é carregado para o contexto.

URIs suportados

• file:// - ficheiros locais
• http://, https:// - documentos online
• data: - dados incorporados (Base64)

Segurança

Do README oficial:

Por predefinição, está associado a localhost. Se o executar por HTTP/SSE (opção --http --host 127.0.0.1 --port 3001), não exponha a porta externamente sem um proxy inverso autenticado.

Que método deve escolher para a sua tarefa?#

Tabela comparativa alargada:

O Marker apresenta valores de precisão impressionantes em testes de referência:

Mas o Marker precisa de uma GPU para atingir uma boa velocidade e inclui modelos de aprendizagem automática. Para a maioria das tarefas (PDFs de texto normal), o PyMuPDF4LLM ou o MarkItDown dão conta do recado em segundos, sem GPU.

Uma regra simples para escolher

1. Um ou dois PDFs, preciso deles rapidamente - MarkItDown CLI.
2. Dezenas de PDFs, preciso de automatização - servidor MCP do MarkItDown ou PyMuPDF4LLM num script.
3. PDFs com ligações e imagens em que é importante preservar a estrutura - PyMuPDF4LLM.
4. RAG em produção para empresas, em que a estabilidade das tabelas é importante - Docling.
5. Artigos científicos com fórmulas - Marker.
6. Não quero pensar no assunto; deixo o Claude converter o PDF - servidor MCP do MarkItDown.

Como escrever um script pronto a usar para converter automaticamente uma pasta de documentos?#

Um exemplo prático: imagine que tem 40 relatórios PDF e PPTX de clientes numa pasta — extratos de corretagem, contratos e apresentações. Carregar a pasta diretamente para o Claude não serve de nada: a janela de contexto ficará cheia de informação antes da primeira resposta. Execute o script abaixo em toda a pasta de uma só vez e depois continue a trabalhar com ficheiros .md leves em vez de PDFs volumosos.

Guarde este script como scripts/docs-to-md.sh na raiz do projeto:

#!/bin/bash
# docs-to-md.sh - converte todos os documentos de uma pasta para Markdown usando o MarkItDown
# Utilização: bash docs-to-md.sh ./documents

set -e

INPUT_DIR="${1:-./documents}"
OUTPUT_DIR="${INPUT_DIR}/_md"

mkdir -p "$OUTPUT_DIR"

echo "Scanning $INPUT_DIR..."

for file in "$INPUT_DIR"/*.{pdf,docx,pptx,xlsx}; do
  [ -f "$file" ] || continue

  basename=$(basename "$file")
  name="${basename%.*}"
  output="$OUTPUT_DIR/${name}.md"

  if [ -f "$output" ] && [ "$output" -nt "$file" ]; then
    echo "Skipping $basename (already converted)"
    continue
  fi

  echo "Converting $basename..."
  markitdown "$file" > "$output"
done

echo "Done. Results are in $OUTPUT_DIR"

Torne-o executável:

chmod +x scripts/docs-to-md.sh

Execute-o:

bash scripts/docs-to-md.sh ./reports

Após a execução, ./reports/_md/ contém versões .md de todos os documentos. Adicione-as ao Claude Code com @reports/_md/ e trabalhe com o texto comprimido em vez dos PDFs.

O script ignora automaticamente os ficheiros que já foram convertidos (se o ficheiro .md for mais recente do que o original) — voltar a executá-lo é barato e não recalcula tudo.

Idempotência e conversão incremental

Se quiser que o script detete PDFs que foram alterados (guardados novamente com o mesmo nome), adicione uma verificação do hash do conteúdo:

hash=$(shasum -a 256 "$file" | cut -d' ' -f1)
hash_file="$OUTPUT_DIR/.${name}.sha256"

if [ -f "$hash_file" ] && [ "$(cat "$hash_file")" = "$hash" ]; then
  echo "Skipping $basename (hash matches)"
  continue
fi

markitdown "$file" > "$output"
echo "$hash" > "$hash_file"

Esta versão só volta a converter um ficheiro se o respetivo conteúdo tiver sido alterado.

Quando é que um PDF no Claude continua a ser melhor do que Markdown?#

Três situações em que a conversão para Markdown fica aquém:

1. Análise visual de diagramas e gráficos

Se o Claude precisar de «ler» um gráfico — uma curva de preços, um diagrama de processos ou um diagrama de arquitetura — essa informação não está no Markdown. O Markdown preserva apenas as legendas das figuras; a própria figura perde-se.

Solução: carregue o PDF e ative explicitamente o modo visual. Na API do Claude, a opção funciona automaticamente; no AWS Bedrock, precisa da opção citations.

2. Tabelas complexas com células unidas

As tabelas Markdown são planas. Se o PDF tiver uma tabela com células unidas, cabeçalhos com vários níveis ou subtabelas aninhadas, o conversor irá achatá-la ou perder as relações entre os elementos.

Solução: utilize diretamente o PDF, utilize o Docling (que lida melhor com tabelas complexas) ou formate a tabela manualmente após a conversão.

3. Documentos como artefactos com referências a páginas

Em documentos jurídicos, contratos e atas, é importante poder citar «página 7, parágrafo 3». Os números das páginas perdem-se no Markdown.

Solução: PDF + Files API + colocação de prompts em cache. Carregue o documento uma vez e depois faça referência a ele por file_id; o Claude vê a paginação e pode citar páginas específicas.

Documentos curtos

Se um PDF tiver menos de 2 páginas e só o utilizar uma vez, não vale a pena convertê-lo. 5 000 tokens para um PDF contra 800 para Markdown não representa uma poupança suficiente para justificar a instalação do MarkItDown.

O ponto de equilíbrio situa-se em cerca de 5 ou mais páginas ou 2 ou mais utilizações do mesmo documento. Abaixo desses valores, carregue o PDF diretamente; acima deles, converta-o.

Quais são os 5 erros mais comuns que as pessoas cometem com PDFs no Claude?#

1. Carregar o mesmo PDF numa conversa nova de cada vez

O Claude Pro tem um limite de mensagens ao longo de 5 horas — um relatório de 50 páginas pode consumi-lo por inteiro antes de fazer uma segunda pergunta.

Há um princípio simples para esta situação: uma tarefa — uma conversa. Quando a IA começa a consumir uma quantidade absurda de tokens, isso significa que está a enfiar tudo numa só conversa e a adicionar o PDF vezes sem conta. Mantenha uma microtarefa em cada janela. Converta o documento para Markdown uma vez e depois adicione o ficheiro .md a cada janela nova, juntamente com o projeto. O círculo da janela de contexto não ficará amarelo.

Solução: converta-o para Markdown uma vez ou utilize a Files API com file_id e colocação de prompts em cache.

2. Uma captura de ecrã em vez de texto

Um exemplo típico: alguém quer mostrar ao Claude um excerto de código ou uma tabela, faz uma captura de ecrã de todo o ecrã de 1920×1080 e pergunta-se porque é que o limite se esgotou após 5 pedidos.

Uma captura de ecrã de 1000×1000 píxeis custa cerca de 1 300 tokens. O mesmo texto copiado à mão custa 50–100 tokens. É uma diferença de 13–26 vezes.

Solução: recorte as capturas de ecrã para incluir apenas a parte importante ou, melhor ainda, copie diretamente o texto.

3. Um PDF digitalizado sem OCR

O MarkItDown não consegue fazer OCR. Se converter um documento digitalizado, o resultado será um ficheiro .md vazio (ou com 3 linhas de ruído).

Solução: para documentos digitalizados, utilize o PyMuPDF4LLM (com OCR inteligente integrado) ou o Docling.

4. Ignorar o limite de 100 páginas

A documentação da Anthropic indica um limite de 600 páginas por pedido — mas, na prática, o limite para modelos com contexto de 200K (Sonnet 4.x, Opus 4.x) é de 100 páginas. O limite de 600 páginas destina-se a modelos mais antigos ou a níveis especiais.

Se carregar um relatório de 150 páginas no Sonnet 4.6, receberá um erro ou, pior ainda, o Claude processará apenas as primeiras 100 páginas e comportar-se-á como se tivesse lido o documento inteiro.

Solução: divida PDFs longos em partes antes de os carregar. Ou converta-os para Markdown — não há limite de páginas, apenas de tokens.

5. Não utilizar a colocação de prompts em cache para pedidos repetidos

Se trabalhar com o mesmo documento através da API, envolva-o em cache_control: ephemeral. Os pedidos repetidos dentro de 5 minutos custam 10% do preço inicial. Um pedido custa mais; os restantes têm um desconto de 90%.

Solução: ative a colocação de prompts em cache por predefinição para tudo o que carregar mais do que uma vez.

O que se segue: engenharia de contexto#

Converter PDF para Markdown é uma forma de poupar tokens. Por si só, não torna as respostas do Claude mais precisas. A precisão resulta da engenharia de contexto — a disciplina que define aquilo que coloca no contexto do modelo antes de fazer uma pergunta.

Se o seu CLAUDE.md tiver 800 linhas, o projeto tiver 10 servidores MCP desnecessários e adicionar um PDF de 100 páginas, a conversão para Markdown evitará uma fuga, mas as outras três continuarão. É por isso que estes guias abordam:

• Para onde vão os tokens no Claude Code - 9 padrões de fuga de contexto, não apenas PDFs.
• Engenharia de Contexto em 2026 - a gestão sistemática do contexto.
• Modo Plan no Claude Code - modo de planeamento antes de o Claude começar a escrever código.