PDF dans Claude Code : conversion, tokens et préservation de la structure

Que devient un PDF dans Claude, et pourquoi chaque page coûte-t-elle 1 500 à 3 000 tokens ?#

La documentation officielle d’Anthropic décrit le processus en trois étapes simples :

Cela semble logique, mais les coûts de traitement augmentent de façon linéaire avec le nombre de pages. Et voici le chiffre qui explique pourquoi un seul PDF suffit à épuiser votre limite d’utilisation :

Pour mesurer l’ampleur de ce coût, Anthropic a testé le même PDF de 3 pages sur Bedrock selon deux modes. En mode texte (Converse Document Chat), il a utilisé environ 1 000 tokens. Avec l’analyse visuelle (Claude PDF Chat), il en a utilisé environ 7 000. L’ajout des images rend le traitement 7 fois plus coûteux.

Les captures d’écran des pages font encore pire. Une capture d’écran de 1000×1000 pixels coûte environ 1 300 tokens.

Le mécanisme est simple : les PDF coûtent cher parce que Claude ne se fie pas à son OCR. Il utilise à la fois le texte et l’image pour les comparer — et vous payez les deux couches en même temps. Pour les documents volumineux, vous pouvez procéder autrement : enregistrez le fichier en Markdown dans le dossier de votre projet et dites à Claude : « voici un document qui contient des informations — répartis-les ». Il distribuera le contenu dans ses propres fichiers et continuera à travailler à partir du texte organisé, au lieu de tout consommer d’un coup.

Quelle quantité de tokens un PDF consomme-t-il dans une tâche courante ?#

Voici les chiffres précis (modèle Sonnet 4.x, entrée à 3 $ par million de tokens) :

Et cela ne concerne qu’un seul cycle de 4 demandes. Ensuite, la mise en cache des prompts entre en jeu (TTL de 5 minutes par défaut, jusqu’à 1 heure avec une offre étendue, et jusqu’à 90 % de réduction sur les appels répétés pendant la période) — les économies se multiplient.

Chaque fois que vous téléversez le même PDF dans un nouveau chat, Claude le relit ; le cache n’est pas conservé d’un chat à l’autre.

Convertir une fois ce PDF de 15 pages en Markdown puis l’ajouter à chacun des quatre chats donne, dans cet exemple, 15 × 300 × 4 = 18 000 tokens d’entrée au lieu de 135 000. Les 300 tokens par page convertie et 2 250 par page PDF sont des hypothèses, pas des constantes. Comptez votre document réel et vérifiez la conversion avant d’estimer les économies.

L’écart est encore plus important avec un abonnement Claude Pro. Un seul rapport de 100 pages peut épuiser toute la limite de 5 heures. Après conversion en Markdown, plus de 10 documents de ce type tiennent dans le même budget.

Quelles sont les limites de l’API Anthropic pour les PDF en 2026 ?#

La documentation d’Anthropic indique les limites dès le début (à jour au 31 mai 2026) :

Claude.ai (l’application web grand public) applique des limites différentes : 500 MB maximum par fichier et jusqu’à 20 fichiers dans un chat. Mais l’analyse visuelle ne fonctionne que pour les PDF de 100 pages maximum — au-delà, Claude ne voit que le texte, sans les graphiques ni les diagrammes.

Voici trois façons d’envoyer un PDF via l’API :

1. Par URL - "source": {"type": "url", "url": "..."} - la méthode la plus simple lorsque le document est en ligne.
2. En Base64 - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - pour les fichiers locaux.
3. Via la Files API - "source": {"type": "file", "file_id": "file_abc123"} - pour les requêtes répétées ; nécessite l’en-tête bêta anthropic-beta: files-api-2025-04-14.

La Files API est le principal moyen d’économiser lorsque vous travaillez sur le même PDF dans différents chats. Téléversez-le une fois, récupérez un file_id, puis utilisez-le pour toutes les interactions. Avec cache_control: ephemeral, les appels répétés coûtent 10 % du tarif normal.

Anthropic donne également des conseils officiels pour réduire l’utilisation :

Méthode 1 : comment configurer MarkItDown en 5 minutes ?#

MarkItDown est un projet officiel de Microsoft maintenu par l’équipe AutoGen. Sur GitHub, il compte 134 mille étoiles et 9,2 mille forks (à la fin mai 2026). Son objectif est formulé directement dans le README :

Formats pris en charge :

• Documents : PDF, DOCX, PPTX, XLSX
• Web : HTML, JSON, XML, CSV
• Médias : audio avec transcription, images avec EXIF et OCR, vidéos YouTube (via les sous-titres)
• Archives : ZIP, EPub
• Autres : toutes les pièces jointes des fichiers Outlook MSG

Installation

Prérequis : Python 3.10+ (généralement déjà installé sur macOS ; sous Windows, vous devez l’installer séparément).

pip install 'markitdown[all]'

Si vous n’avez pas besoin de tous les formats, vous pouvez en installer une sélection :

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

Convertir un seul fichier

Le cas le plus simple :

markitdown document.pdf > document.md

Le fichier document.md apparaît alors dans le dossier courant. Ajoutez-le à Claude Code avec @document.md ou placez-le simplement à côté de votre projet.

API Python

Pour intégrer l’outil à votre script :

from markitdown import MarkItDown

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

# You can save it straight away:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

Ce que MarkItDown NE PEUT PAS faire

• OCR des PDF numérisés - il ne renvoie rien. Pour les documents numérisés, utilisez PyMuPDF4LLM ou Docling.
• Mises en page complexes à plusieurs colonnes - l’ordre de lecture peut être mélangé.
• URLs intégrées aux PDF - elles ne sont pas conservées.

Pour les PDF simples (rapports, articles, documentation), MarkItDown est le meilleur choix : un outil polyvalent qui s’installe en une minute et ne nécessite aucune connaissance de Python. Les mesures sur des documents contenant du texte cyrillique et des scans sont présentées dans l’analyse consacrée à la façon de convertir un PDF en texte pour l’IA.

Méthode 2 : qu’offre PyMuPDF4LLM, et quand est-il préférable ?#

MarkItDown offre une grande diversité de formats ; PyMuPDF4LLM offre un traitement approfondi des PDF.

La version au 31 mai 2026 est la 1.27.2.3 (publiée le 24 avril 2026).

Fonctionnalités incluses

• Pages à plusieurs colonnes avec le bon ordre de lecture
• Conversion des tableaux en Markdown compatible avec GitHub
• Suppression automatique des en-têtes et pieds de page
• Extraction des images avec des liens relatifs vers un dossier séparé
• OCR intelligente : appliquée uniquement aux zones illisibles, elle économise environ 50 % du temps de traitement
• Moteur natif C, aucun GPU nécessaire

Installation

pip install pymupdf4llm

Utilisation

import pymupdf4llm

# Basic use - straight to Markdown:
md_text = pymupdf4llm.to_markdown("document.pdf")

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

En une ligne, comme promis :

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

Quand choisir PyMuPDF4LLM plutôt que MarkItDown

• Lorsque le PDF contient de nombreux liens que vous devez préserver (MarkItDown les perd).
• Lorsque le document est numérisé et que vous avez besoin de l’OCR.
• Lorsque vous devez traiter rapidement des milliers de fichiers en local : le moteur natif C est plus rapide que les wrappers Python.
• Lorsque vous avez besoin des images du PDF dans un dossier séparé pour les traiter ensuite.

Détail de la licence (important pour les entreprises)

PyMuPDF4LLM est proposé sous double licence : AGPL v3 OU licence commerciale Artifex.

AGPL signifie que : si vous utilisez la bibliothèque dans un SaaS public, vous devez publier tout le code source de votre service sous la même licence AGPL. Pour un usage interne (votre script sur votre ordinateur), il n’y a aucune restriction.

Pour développer un produit commercial sans divulguer le code, achetez une licence auprès d’Artifex (artifex.com). Les prix ne sont pas publiés ; demandez-les au service commercial.

Si vous développez un produit pour des clients, vérifiez la licence dès le début. MarkItDown (MIT) et Docling (MIT) sont plus adaptés au SaaS.

Méthode 3 : comment connecter le serveur MCP MarkItDown à Claude Code ?#

Le mode CLI de MarkItDown signifie : « Je convertis les fichiers manuellement à l’avance » ; le serveur MCP signifie : « Claude Code décide quand les convertir ».

Installation

Vous avez besoin du gestionnaire de paquets uv. Il n’est pas nécessaire d’installer le serveur séparément ; uv le télécharge lors de sa première exécution.

Configuration dans Claude Code

Une seule commande connecte le serveur à tous vos projets ; la version est épinglée :

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

L’entrée markitdown doit indiquer « Connected ». Au premier lancement, environ soixante-dix paquets sont téléchargés, ce qui prend jusqu’à une minute. Ensuite, le serveur démarre en une ou deux secondes.

Voici pourquoi la commande nécessite ces deux variables. ORT_DISABLE_TELEMETRY=1 désactive les statistiques que le moteur onnxruntime intégré au serveur envoie à Microsoft par défaut sur Mac et Linux. UV_PYTHON=3.12 exécute le serveur avec Python 3.12, pour lequel des paquets précompilés sont disponibles sur Windows, Linux et les Mac dotés d’Apple Silicon. Sur les Mac Intel et sous macOS 13 ou une version antérieure, le serveur ne s’installe pas avec Python 3.14. Il y a une réserve concernant Intel et la version 3.12 : uv compilera la bibliothèque cryptography à partir du code source, car aucun paquet précompilé pour Intel n’est disponible depuis juin 2026. L’installation prend plus de temps et peut échouer. Si Python 3.12 n’est pas installé, uv le téléchargera.

Le serveur s’exécute directement sur votre ordinateur et peut ouvrir tous les fichiers auxquels vous avez accès. Si Claude Code était ouvert, redémarrez-le ; markitdown apparaîtra dans la liste des serveurs MCP.

Utilisation

Dans Claude Code, dites simplement :

Convertis /Users/your-user/Documents/report.pdf en Markdown et analyse les points principaux.

Claude appelle lui-même convert_to_markdown(uri), récupère le Markdown et travaille avec celui-ci : le PDF n’est pas chargé dans le contexte.

URI prises en charge

• file:// - fichiers locaux
• http://, https:// - documents en ligne
• data: - données intégrées (Base64)

Sécurité

D’après le README officiel :

Par défaut, il est lié à localhost. Si vous l’exécutez en HTTP/SSE (option --http --host 127.0.0.1 --port 3001), n’exposez pas le port à l’extérieur sans proxy inverse avec authentification.

Quelle méthode choisir pour votre tâche ?#

Tableau comparatif détaillé :

Marker affiche des résultats impressionnants dans les tests de référence :

Mais Marker nécessite un GPU pour atteindre une bonne vitesse et s’accompagne de modèles d’apprentissage automatique. Pour la plupart des tâches sur des PDF contenant du texte ordinaire, PyMuPDF4LLM ou MarkItDown font l’affaire en quelques secondes, sans GPU.

Une règle simple pour choisir

1. Un ou deux PDF, besoin d’aller vite - MarkItDown CLI.
2. Des dizaines de PDF, besoin d’automatiser - serveur MCP MarkItDown ou PyMuPDF4LLM dans un script.
3. PDF avec liens et images dont la structure doit être préservée - PyMuPDF4LLM.
4. RAG en production pour une entreprise, où la stabilité des tableaux compte - Docling.
5. Articles scientifiques avec formules - Marker.
6. Vous ne voulez pas y penser et préférez laisser Claude convertir les fichiers - serveur MCP MarkItDown.

Comment écrire un script prêt à l’emploi pour convertir automatiquement un dossier de documents ?#

Exemple pratique : imaginons que vous ayez 40 rapports PDF et PPTX de clients dans un dossier — relevés de courtage, contrats et présentations. Téléverser directement le dossier dans Claude ne sert à rien : la fenêtre de contexte sera remplie avant la première réponse. Traitez tout le dossier en une seule passe avec le script ci-dessous, puis travaillez avec des fichiers .md légers plutôt qu’avec de gros PDF.

Enregistrez ce script sous scripts/docs-to-md.sh à la racine du projet :

#!/bin/bash
# docs-to-md.sh - convertit tous les documents d'un dossier en Markdown avec MarkItDown
# Utilisation : 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"

Rendez-le exécutable :

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

Exécutez-le :

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

Une fois le script exécuté, ./reports/_md/ contient les versions .md de tous les documents. Ajoutez-les à Claude Code avec @reports/_md/ et travaillez avec le texte compressé plutôt qu’avec les PDF.

Le script ignore automatiquement les fichiers déjà convertis (si le fichier .md est plus récent que la source) ; une nouvelle exécution est rapide et ne recalcule pas tout.

Idempotence et conversion incrémentielle

Pour que le script détecte les PDF qui ont été modifiés et enregistrés sous le même nom, ajoutez une vérification de l’empreinte du contenu :

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"

Cette version reconvertit un fichier uniquement si son contenu a changé.

Quand un PDF dans Claude reste-t-il préférable au Markdown ?#

Voici trois cas où la conversion en Markdown montre ses limites :

1. Analyse visuelle de diagrammes et de graphiques

Si Claude doit « lire » un graphique — une courbe de prix, un schéma de processus ou un diagramme d’architecture — ces informations ne figurent pas dans le Markdown. Celui-ci ne conserve que les légendes des figures ; la figure elle-même est perdue.

Solution : téléversez le PDF et activez explicitement le mode visuel. Dans l’API Claude, le paramètre fonctionne automatiquement ; sur AWS Bedrock, vous avez besoin du paramètre citations.

2. Tableaux complexes avec cellules fusionnées

Les tableaux Markdown sont plats. Si le PDF contient un tableau avec des cellules fusionnées, des en-têtes à plusieurs niveaux ou des sous-tableaux imbriqués, le convertisseur l’aplatira ou en perdra les relations.

Solution : utilisez directement le PDF, choisissez Docling (qui gère le mieux les tableaux complexes) ou mettez le tableau en forme manuellement après la conversion.

3. Documents utilisés comme pièces avec références aux pages

Pour les documents juridiques, les contrats et les comptes rendus, il est important de pouvoir citer « page 7, paragraphe 3 ». Les numéros de page disparaissent en Markdown.

Solution : PDF + Files API + mise en cache des prompts. Téléversez le document une fois, puis référencez-le avec file_id ; Claude voit la pagination et peut citer des pages précises.

Documents courts

Si un PDF fait moins de 2 pages et que vous ne l’utilisez qu’une fois, la conversion ne vaut pas la peine. 5 000 tokens pour un PDF contre 800 pour le Markdown : l’économie ne justifie pas d’installer MarkItDown.

Le seuil de rentabilité se situe autour de 5 pages ou plus, ou de 2 utilisations ou plus du même document. En dessous, téléversez directement le PDF ; au-delà, convertissez-le.

Quelles sont les 5 erreurs les plus fréquentes avec les PDF dans Claude ?#

1. Téléverser le même PDF dans un nouveau chat à chaque fois

Claude Pro impose une limite de messages sur une période de 5 heures : un seul rapport de 50 pages peut l’épuiser avant même que vous posiez une deuxième question.

Un principe simple peut vous aider : une tâche — un chat. Quand l’IA consomme un nombre absurde de tokens, c’est que vous entassez probablement tout dans un seul chat et que vous y ajoutez le PDF encore et encore. Limitez chaque fenêtre à une petite tâche. Convertissez le document une fois en Markdown, puis ajoutez le fichier .md à chaque nouvelle fenêtre avec le projet. Le cercle de la fenêtre de contexte ne deviendra pas jaune.

Solution : convertissez-le une fois en Markdown, ou utilisez la Files API avec file_id et la mise en cache des prompts.

2. Une capture d’écran au lieu du texte

Un exemple courant : quelqu’un veut montrer à Claude un extrait de code ou un tableau, prend une capture de l’écran entier en 1920×1080 et se demande pourquoi la limite est épuisée après 5 demandes.

Une capture d’écran de 1000×1000 pixels coûte environ 1 300 tokens. Le même texte copié à la main coûte 50 à 100 tokens. La différence est de 13 à 26 fois.

Solution : recadrez les captures d’écran au plus près (pour ne garder que la partie importante) ou, mieux encore, copiez directement le texte.

3. Un PDF numérisé sans OCR

MarkItDown ne peut pas effectuer d’OCR. Si vous convertissez un document numérisé, le résultat sera un fichier .md vide (ou 3 lignes de texte illisible).

Solution : pour les scans, utilisez PyMuPDF4LLM avec son OCR intelligente intégrée ou Docling.

4. Ignorer la limite de 100 pages

La documentation d’Anthropic indique une limite de 600 pages par requête — mais, en pratique, la limite pour les modèles avec un contexte de 200K (Sonnet 4.x, Opus 4.x) est de 100 pages. La limite de 600 pages est destinée aux anciens modèles ou à des offres spéciales.

Si vous téléversez un rapport de 150 pages dans Sonnet 4.6, vous obtiendrez une erreur ou, pire encore, Claude ne traitera que les 100 premières pages tout en faisant comme s’il avait lu le document entier.

Solution : divisez les PDF longs en parties avant de les téléverser. Vous pouvez aussi les convertir en Markdown : il n’y a pas de limite de pages, seulement une limite de tokens.

5. Ne pas utiliser la mise en cache des prompts pour les demandes répétées

Si vous travaillez avec le même document via l’API, enveloppez-le dans cache_control: ephemeral. Les demandes répétées dans les 5 minutes coûtent 10 % du prix initial. La première demande coûte davantage ; les suivantes bénéficient d’une réduction de 90 %.

Solution : activez par défaut la mise en cache des prompts pour tout document que vous téléversez plus d’une fois.

Et ensuite : l’ingénierie du contexte#

Convertir un PDF en Markdown est une façon d’économiser des tokens. À elle seule, cette conversion ne rend pas les réponses de Claude plus précises. La précision vient de l’ingénierie du contexte — la discipline qui consiste à choisir ce que vous ajoutez au contexte du modèle avant de poser une question.

Si votre CLAUDE.md contient 800 lignes, que votre projet compte 10 serveurs MCP inutiles et que vous ajoutez un PDF de 100 pages, la conversion en Markdown évitera une fuite, mais les trois autres subsisteront. C’est pourquoi ces guides abordent les sujets suivants :

• Où vont les tokens dans Claude Code - 9 façons de gaspiller le contexte, pas seulement avec les PDF.
• L’ingénierie du contexte en 2026 - gérer le contexte de façon systématique.
• Le mode Plan dans Claude Code - le mode de planification avant que Claude commence à écrire du code.