# PDFs no Claude Code: conversão, tokens e preservação da estrutura > MarkItDown, PyMuPDF4LLM, MCP, scripts completos de conversão, limites de PDF e situações em que a análise visual é mais importante do que a poupança de tokens. Source: https://ailoot.ai/blog/pt-pt/pdf-claude-code-markdown/ Canonical: https://ailoot.ai/blog/pt-pt/pdf-claude-code-markdown/ Language: pt-PT Publisher: Ailoot (https://ailoot.ai/) Translation: guide-196 Revision: sha256-0fe21f599ce2538bc9cc6b5586c5d741c3251b8adc6701bfa34b38a36fd3d211
Ideia principal Cada página de PDF no Claude Code custa 1 500–3 000 tokens antes da primeira pergunta — e a Anthropic afirma-o claramente na sua documentação. No cálculo ilustrativo abaixo, um relatório de 15 páginas em 4 chats usa 135 000 tokens PDF de entrada por cerca de $0.40, contra 18 000 tokens Markdown por $0.054, cerca de 87% menos. Pressupõe 2 250 tokens PDF ou 300 Markdown por página à tarifa de entrada do exemplo; os documentos reais variam. Este guia apresenta três métodos de conversão (MarkItDown, PyMuPDF4LLM e um servidor MCP) e um script bash pronto a usar para uma pasta de documentos.
As instruções práticas para utilizar a Ailoot estão na [documentação](https://ailoot.ai/docs/).
## O que acontece a um PDF no Claude e porque custa cada página 1 500–3 000 tokens?
Ideia principal Quando carrega um PDF no Claude Code, este não o lê como um ficheiro de texto. Primeiro, cada página é convertida numa imagem; depois, o texto é extraído e ambas as camadas — a imagem e o texto — são adicionadas ao contexto em conjunto. É por isso que uma página ocupa 1 500–3 000 tokens e um documento de 50 páginas pode consumir 75 000–150 000 tokens antes de fazer a primeira pergunta.
A documentação oficial da Anthropic descreve o processo em três passos simples:

O sistema converte cada página do documento numa imagem. O texto de cada página é extraído e apresentado juntamente com a imagem da página. O Claude analisa tanto o texto como as imagens para compreender melhor o documento.

— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support
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:

Cada página utiliza normalmente 1 500–3 000 tokens, consoante a densidade do conteúdo. Como cada página é convertida numa imagem, aplica-se o mesmo custo que às imagens normais.

— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support
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?
Ideia principal Considere um relatório público de 15 páginas em 4 contextos: análise, citações, tradução e resumo. Assuma 2 250 tokens de entrada por página PDF, 300 por página Markdown convertida e a mesma tarifa de entrada. Recarregar o PDF dá 135 000 tokens, cerca de $0.40; Markdown dá 18 000, ou $0.054. A poupança aproximada de 87% resulta desses pressupostos, não de medições de todos os PDFs.
Os valores específicos (modelo Sonnet 4.x, entrada a 3 $ por milhão de tokens): | Método | Tokens (15 páginas, 4 conversas) | Custo | |------------------------------|-----------------------------|-------------| | PDF carregado diretamente 4 vezes | 15 × 2250 × 4 = **135 000** | ~0,40 $ | | PDF → Markdown + 4 conversas | 15 × 300 × 4 = **18 000** | ~0,054 $ | | Poupança | **−87%** | **−0,35 $** | 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?
Ideia principal A Anthropic impõe limites rigorosos: no máximo 32 MB por pedido (incluindo todo o conteúdo, não apenas o PDF) e um máximo de 600 páginas por pedido. Mas o limite é inferior para os modelos atuais Sonnet 4.x e Opus 4.x com contexto de 200K: **100 páginas**. Pode enviar um PDF de três formas: por URL, em Base64 ou através da Files API para reutilização com `file_id`. A Files API, combinada com a divisão em partes, é usada para documentos longos.
A documentação da Anthropic apresenta os limites no início (atuais a 31 de maio de 2026): | Requisito | Limite | |-----------------------------|--------------------------------------------| | Tamanho máximo do pedido | 32 MB (varia consoante a plataforma) | | Número máximo de páginas por pedido | 600 (100 para modelos com contexto de 200K tokens) | | Formato | PDF normal sem palavra-passe nem encriptação |

Ambos os limites se aplicam ao corpo inteiro do pedido, incluindo o conteúdo enviado juntamente com o PDF. Para PDFs grandes, utilize a Files API e faça referência aos ficheiros com file_id para manter o corpo do pedido pequeno.

— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support
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:

PDFs densos (com muito texto pequeno, tabelas complexas ou muitos elementos gráficos) podem preencher a janela de contexto antes de atingir o limite de páginas. Experimente dividir o documento em secções; no caso de ficheiros grandes, reduza a resolução das imagens incorporadas antes de os carregar.

— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support
## Método 1: Como configurar o MarkItDown em 5 minutos?
Ideia principal O MarkItDown é um utilitário Python da equipa Microsoft AutoGen que converte PDFs, DOCX, PPTX, XLSX, HTML, áudio, imagens e até vídeos do YouTube em Markdown limpo. Tem 134 mil estrelas no GitHub, uma licença MIT e instala-se com um único comando: `pip install 'markitdown[all]'`. Também é igualmente simples de utilizar: `markitdown document.pdf > document.md`. É a ferramenta mais versátil para converter ficheiros antes de utilizar o Claude Code.
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:

Um utilitário Python leve para converter ficheiros em Markdown para utilização com LLMs e pipelines de análise de texto.

— Microsoft, https://github.com/microsoft/markitdown
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). ```bash pip install 'markitdown[all]' ``` Se não precisar de todos os formatos, pode instalar apenas alguns: ```bash pip install 'markitdown[pdf, docx, pptx]' ``` ### Converter um único ficheiro O caso mais simples: ```bash 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: ```python 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](https://ailoot.ai/blog/pt-pt/markitdown-pdf-word-to-text/). ## Método 2: O que oferece o PyMuPDF4LLM e quando é melhor?
Ideia principal O PyMuPDF4LLM é um projeto da Artifex Software baseado no motor nativo MuPDF em C. É o conversor de PDF mais rápido (não precisa de GPU); o OCR inteligente só é aplicado às zonas ilegíveis e reduz o tempo de processamento em 50%. É a única ferramenta popular que preserva URLs e imagens incorporadas em PDFs. A desvantagem é a licença dupla AGPL v3 / comercial da Artifex: em projetos SaaS, a AGPL significa que tem de publicar o seu código.
O MarkItDown oferece uma grande variedade de formatos; o PyMuPDF4LLM oferece um processamento de PDF mais aprofundado.

Uma extensão leve do PyMuPDF que transforma PDFs em dados limpos e estruturados com uma configuração mínima.

— Artifex Software, https://pymupdf.readthedocs.io/en/latest/pymupdf4llm/
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 ```bash pip install pymupdf4llm ``` ### Utilização ```python 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: ```bash 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? {#método-3-como-ligar-o-servidor-mcp-do-markitdown-ao-claude-code}
Ideia principal O servidor MCP do MarkItDown é o mesmo MarkItDown envolvido no protocolo MCP, pelo que o Claude Code pode converter PDFs em tempo real sem carregar o ficheiro original para o contexto. Ligue-o com um único comando através do uv; a versão está fixada: `markitdown-mcp@0.0.1a7`. A ferramenta disponibilizada ao Claude é `convert_to_markdown(uri)`. Em inatividade, o custo é de cerca de 110 tokens para a descrição da ferramenta e zero quando não é necessária.
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: ```bash 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:

O servidor não suporta autorização e é executado com as permissões do utilizador que o iniciou.

— Microsoft, https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
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?
Ideia principal O MarkItDown é a opção polivalente se trabalhar com vários formatos (PDF + DOCX + PPTX + YouTube) e precisar de um comando CLI rápido. O PyMuPDF4LLM é especializado em PDF: mais rápido, com OCR e preservação de ligações, mas com a armadilha da AGPL para SaaS. O Docling está preparado para produção e é o melhor a lidar com tabelas e fórmulas. O Marker destina-se a artigos científicos com matemática. O servidor MCP é para quando não quer pensar na conversão e pretende que o Claude Code decida por si.
Tabela comparativa alargada: | Ferramenta | Estrelas no GitHub | Mais indicada para | Velocidade | Licença | |----|----|----|----|----| | **MarkItDown** (Microsoft) | 134k | PDF + DOCX + PPTX + YouTube + áudio | Média | MIT | | **PyMuPDF4LLM** (Artifex) | \- | PDF nativo, OCR, URLs incorporados | A mais rápida (sem GPU) | AGPL v3 / comercial | | **Docling** (IBM Research) | 60.7k | RAG em produção, tabelas, fórmulas | Média | MIT | | **Marker** (datalab.to) | 35.6k | PDFs científicos, arXiv, fórmulas | Elevada (com GPU) | GPL-3.0 + Open Rail-M | | **MinerU** | \- | Documentos CJK (chinês/japonês) | Elevada | Apache-2.0 | O Marker apresenta valores de precisão impressionantes em testes de referência:

0,18 segundos por página numa GPU H100 (122 páginas por segundo). Precisão de 95,67% contra 84,24% do Llamaparse e 86,43% do Mathpix. Em artigos científicos, 96,67%.

— datalab.to, https://github.com/datalab-to/marker
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?
Ideia principal A abordagem mais prática é um script bash que percorre uma pasta de projeto, converte todos os ficheiros PDF, DOCX e PPTX para Markdown e coloca-os numa subpasta `_md/`. Configure-o uma vez e qualquer nova pasta de documentos passa a ser «legível pelo Claude» num só processamento. Depois, adicione `_md/` ao Claude Code com `@_md/` e trabalhe com o texto comprimido.
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: ```bash #!/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: ```bash chmod +x scripts/docs-to-md.sh ``` Execute-o: ```bash 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: ```bash 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?
Ideia principal A conversão para Markdown perde três coisas: elementos visuais (diagramas, gráficos, plantas), tabelas complexas com células unidas e legendas, e a formatação completa do documento enquanto artefacto (por exemplo, um contrato em que precisa de citar a página). Se estes elementos forem importantes para a tarefa, mantenha o PDF, ative a análise visual e aceite conscientemente esse custo.
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`.

O Claude analisa tanto o texto como as imagens para compreender melhor o documento.

— Anthropic, https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support
### 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?
Ideia principal Os principais problemas: voltar a carregar o mesmo PDF em conversas diferentes em vez de o converter uma vez, não utilizar a colocação de prompts em cache para pedidos repetidos, usar capturas de ecrã em vez de texto, não aplicar OCR a PDFs digitalizados e ignorar o limite de 100 páginas para modelos com contexto de 200K. Cada erro desperdiça dezenas de milhares de tokens sem qualquer motivo.
### 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
Ideia principal Converter PDFs para Markdown é uma técnica de engenharia de contexto, uma nova literacia para trabalhar com IA. Um prompt é uma pergunta. O contexto é tudo o que o Claude vê antes e à volta da pergunta: o prompt de sistema, CLAUDE.md, ficheiros, servidores MCP e o histórico da sessão. Quanto mais limpo for o contexto, mais precisa será a resposta e menos custará. Leia a análise completa no guia «Engenharia de Contexto em 2026».
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](https://ailoot.ai/blog/pt-pt/where-claude-code-tokens-go/) - 9 padrões de fuga de contexto, não apenas PDFs. - [Engenharia de Contexto em 2026](https://ailoot.ai/blog/pt-pt/context-engineering/) - a gestão sistemática do contexto. - [Modo Plan no Claude Code](https://ailoot.ai/blog/pt-pt/claude-code-plan-mode/) - modo de planeamento antes de o Claude começar a escrever código.
### Fontes - [Anthropic - Suporte para PDF (platform.claude.com)](https://platform.claude.com/docs/en/docs/build-with-claude/pdf-support) - [Anthropic - Carregar ficheiros para o Claude (support.claude.com)](https://support.claude.com/en/articles/8241126-upload-files-to-claude) - [Microsoft MarkItDown no GitHub](https://github.com/microsoft/markitdown) - [Servidor MCP do MarkItDown](https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp) - [PyMuPDF4LLM - documentação oficial](https://pymupdf.readthedocs.io/en/latest/pymupdf4llm/) - [Docling no GitHub (IBM Research)](https://github.com/DS4SD/docling) - [Marker no GitHub (datalab.to)](https://github.com/datalab-to/marker)
Continue a explorar a Ailoot em [ailoot.ai](https://ailoot.ai/).
## Perguntas frequentes ### Quantos tokens Markdown usa o exemplo de 15 páginas e quatro chats? Com o pressuposto do artigo de 300 tokens por página convertida, o total é 15 × 300 × 4 = 18 000 tokens de entrada. É uma estimativa ilustrativa; conte os tokens do documento convertido para o seu próprio ficheiro. ### Uma conversão textual basta para qualquer PDF? Não. Compare o Markdown com o PDF, sobretudo tabelas, ordem das páginas e conteúdo dependente de imagens. Compare os tokens só depois de confirmar que a informação necessária à tarefa sobreviveu à conversão. ## Ailoot · A empresa e a sua carteira de projetos A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI. A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões. A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.