Tokens Claude : coûts d’une session Claude Code

Que sont les tokens dans Claude ?

Un token est l’unité de texte que Claude lit et écrit : un fragment de mot, d’environ 3.5 caractères anglais. Ce chiffre vient du glossaire d’Anthropic. En pratique, il représente bien plus d’un token par mot une fois les espaces et la ponctuation comptés. Ainsi, mille mots de prose dépassent largement 1,300 tokens. Le code consomme davantage de tokens par ligne : les accolades, les opérateurs, les underscores et l’indentation produisent davantage de tokens par caractère que l’anglais. Un fichier source de quelques centaines de lignes représente généralement plusieurs milliers de tokens. Un fichier de 2,000 lignes que l’agent décide de lire représente déjà une consommation à cinq chiffres avant même l’écriture d’une seule ligne de nouveau code.

Deux aspects des tokenizers posent souvent problème. Premièrement, ils dépendent du modèle. En juillet 2026, Opus 4.7 et les versions ultérieures, Sonnet 5 et Fable 5 utilisent un tokenizer plus récent qui produit environ 30 % de tokens supplémentaires pour un même texte par rapport aux anciens modèles Claude. L’augmentation exacte dépend du contenu. Cela modifie tous les calculs fondés sur le nombre de tokens, même si le prix par token n’a pas augmenté. Deuxièmement, tiktoken, la bibliothèque utilisée dans presque tous les articles de blog, est le tokenizer d’OpenAI. Elle sous-estime le nombre de tokens de Claude d’environ 15–20 % sur du texte courant, et davantage sur du code. Le seul décompte fiable est celui de l’endpoint count_tokens, présenté ci-dessous.

Le coût réel de votre session de programmation

Chaque facture Claude, qu’il s’agisse d’une facture API ou d’une limite d’abonnement, repose sur un seul compteur : les tokens en entrée et les tokens en sortie. La page tarifaire donne une impression de simplicité : un certain nombre de dollars par million de tokens en entrée, et un autre par million de tokens en sortie. Ce qu’elle n’explique pas, c’est que, dans une session de programmation agentique, le compteur des entrées augmente beaucoup plus vite qu’on ne le pense, car l’intégralité de la conversation est renvoyée à chaque tour. Je vends des infrastructures facturées à la consommation depuis quinze ans, et les tokens sont le premier compteur que je rencontre dont la plupart des clients ne savent réellement pas ce qui le fait tourner. Voici comment lire ce compteur : ce qui compte comme entrée et comme sortie dans une session agentique, pourquoi la boucle de renvoi coûte si cher, comment la mise en cache des prompts modifie le calcul, et quels leviers font réellement varier le montant.

Tout est une entrée : ce que le compteur mesure réellement

On pense payer pour le code écrit par Claude. Dans une session agentique, c’est le petit poste de dépense. Les tokens d’entrée, facturés au tarif le plus bas mais générés en bien plus grande quantité, comprennent :

• Le prompt système. Les propres instructions de l’environnement d’exécution de Claude Code, ainsi que vos fichiers CLAUDE.md et vos fichiers de mémoire, chargés au début de la session et présents dans chaque requête suivante.
• Les définitions des outils. Chaque schéma d’outil que l’agent peut appeler. Chaque serveur MCP que vous connectez augmente cette surcharge fixe. Claude Code diffère toutefois désormais par défaut le chargement complet des définitions des outils MCP. Seuls les noms des outils restent donc dans le contexte jusqu’à la première utilisation d’un outil. Cela réduit le coût sans le supprimer.
• Chaque fichier lu par l’agent. Un Read d’un fichier source place l’intégralité du fichier dans le contexte, où elle reste ensuite.
• Chaque résultat d’outil. Résultats des tests, sortie de grep, sortie du terminal, journaux de build : tout revient sous forme de tokens d’entrée. Une suite de tests en échec qui affiche 8,000 lignes vient de vous facturer l’équivalent d’un petit livre.
• L’intégralité de la conversation jusque-là, renvoyée à chaque tour. Ce point mérite sa propre section.

Le renvoi que personne ne facture

L’API Claude est sans état. Elle ne mémorise pas votre session entre les requêtes, et rien ne le fait. Au tour 2, le client envoie donc le tour 1, la réponse du modèle et votre nouveau message. Au tour 50, il renvoie les tours 1 à 49, chaque fichier lu, chaque résultat d’outil, chaque différence, puis le tour 50. Le modèle relit l’intégralité de la transcription à chaque fois, et chacun de ces tokens relus est facturé comme entrée.

Conséquence : le coût par tour augmente approximativement de façon linéaire avec la durée de la session, tandis que le coût total de la session augmente approximativement de façon quadratique. Un message qui coûte un demi-cent au tour 3 peut coûter vingt fois plus au tour 60, pour la même question d’une ligne, parce qu’il transporte soixante tours de contexte. C’est le fait essentiel qui explique la plupart des demandes concernant une facture trop élevée. Ce n’est pas une particularité de Claude : tout produit LLM qui semble conserver un état repose en réalité sur une API sans état et une boucle de renvoi.

Sortie : ce que vous voyez, et ce que vous ne voyez pas

Les tokens de sortie sont coûteux : leur tarif est cinq fois supérieur à celui des tokens d’entrée pour toute la gamme actuelle ($5/$25 pour Opus 4.8, $3/$15 affiché pour Sonnet 5, $1/$5 pour Haiku 4.5, en juillet 2026). La sortie comprend le texte et le code générés par Claude, ainsi que les tokens de raisonnement : le raisonnement interne effectué par le modèle avant sa réponse. Deux points sont importants. Le raisonnement est facturé au tarif de la sortie et décompté de max_tokens. Une réponse de l’API qui s’arrête avec stop_reason: "max_tokens" et une réponse tronquée signifient souvent que le raisonnement a consommé le budget avant la génération de la réponse. De plus, sur les modèles actuels, le résumé du raisonnement peut ne pas être affiché du tout : Opus 4.8, Sonnet 5 et Fable 5 l’omettent par défaut, mais le raisonnement a bien eu lieu et reste facturé. Invisible ne signifie pas gratuit.

Claude Code active le extended thinking par défaut, car il améliore de manière mesurable les tâches en plusieurs étapes. Le budget par défaut peut atteindre plusieurs dizaines de milliers de tokens par requête. Pour les tâches plus simples, vous pouvez le réduire : diminuez le niveau d’effort avec /effort ou dans /model, ou modifiez les paramètres du thinking dans /config. C’est un véritable levier de réduction des coûts, pas une superstition.

Le cache des prompts change complètement le calcul

Le cache des prompts explique pourquoi la boucle de renvoi ne ruine pas tout le monde. L’API peut mettre en cache un préfixe stable de votre prompt, du prompt système, des définitions d’outils et de l’historique de conversation, puis le servir à la requête suivante pour une fraction du prix. En juillet 2026, les multiplicateurs sont les suivants : une écriture dans le cache coûte 1.25× le tarif d’entrée de base (2× pour la variante d’1 heure), tandis qu’une lecture du cache coûte 0.1×. Les écritures sont facturées avec une surcharge ; les lectures bénéficient d’une remise de 90 %. Une seule lecture suffit déjà à compenser largement le surcoût de l’écriture valable 5 minutes.

Claude Code gère le cache pour vous et, dans une session saine, la quasi-totalité de ce renvoi massif est servie depuis le cache. Mais le cache par défaut reste valide pendant cinq minutes après sa dernière utilisation. Vous vous absentez pour un café qui s’éternise, vous revenez et envoyez un message : le cache a expiré, et tout le préfixe accumulé est réécrit à 1.25× au lieu d’être lu à 0.1×. Dans une session de 150K tokens, ce seul tour à froid coûte plus d’une douzaine de tours à chaud. Voici le résultat contre-intuitif à retenir : un rythme consistant à s’arrêter puis reprendre peut coûter plus cher qu’un travail continu, car chaque période d’inactivité dépassant le TTL transforme le tour suivant, normalement peu coûteux, en réécriture coûteuse. Travaillez par sessions concentrées ; n’alimentez pas progressivement une session volumineuse à raison d’un message toutes les dix minutes.

Si vous appelez l’API depuis votre propre application sur un VPS, vous ne bénéficiez d’aucun de ces mécanismes gratuitement. Le piège classique consiste à interpoler un horodatage ou un ID de requête dans le prompt système. Les octets du préfixe changent alors à chaque requête, ce qui désactive silencieusement la mise en cache. L’indice est usage.cache_read_input_tokens qui reste à zéro pour des appels apparemment identiques.

La formule, avec un exemple détaillé

Ignorez les affirmations selon lesquelles « une session coûte X $ ». Le coût des sessions peut varier d’un facteur 100. La formule à retenir est la suivante :

turn cost = (uncached input      x base input price)
          + (cache writes        x 1.25 x base input price)
          + (cache reads         x 0.10 x base input price)
          + (output incl. thinking x output price)

session cost = sum over all turns

Exemple avec Claude Opus 4.8, qui, en juillet 2026, coûte 5 $ par million de tokens d’entrée et 25 $ par million de tokens de sortie. Prenons un tour en milieu de session avec 80,000 tokens de contexte cumulé : 75,000 lus depuis le cache, 3,000 nouvellement écrits, 2,000 tokens d’entrée nouveaux non mis en cache et 1,500 tokens de sortie, raisonnement compris.

• Lectures du cache : 75,000 × 0.50 $/M = 0.0375 $
• Écritures dans le cache : 3,000 × 6.25 $/M = 0.019 $
• Entrée non mise en cache : 2,000 × 5 $/M = 0.010 $
• Sortie : 1,500 × 25 $/M = 0.0375 $

Soit environ 0.10 $ pour ce tour ; cinquante tours similaires coûtent environ 5 $. Prenons maintenant le même tour après expiration du cache : les 80,000 tokens sont réécrits au tarif de 6.25 $/M, soit 0.50 $ avant la sortie. Le coût est donc environ cinq fois supérieur à celui du tour complet avec un cache actif, pour le même travail. Cet écart résume à lui seul l’impact de la mise en cache. Ces quatre lignes sont également la seule manière fiable de comparer les fournisseurs, car les tarifs affichés ignorent complètement les lectures du cache et le raisonnement. Appliquez ce calcul à trois tâches réelles pour voir où la facture Claude est supérieure ou inférieure à celle d’OpenAI.

Si vous voulez comprendre l’unité de facturation elle-même plutôt que le coût d’un seul tour, voici ce que représente un million de tokens en pages, fichiers et dollars avec le même calcul, mais à un niveau supérieur. Il s’agit d’un ordre de grandeur, pas d’une prévision : selon les chiffres publiés par Anthropic pour les déploiements de Claude Code en entreprise, en juillet 2026, le coût moyen est d’environ 13 $ par développeur et par jour d’activité, et de 150 à 250 $ par mois. 90 % des utilisateurs restent sous 30 $ par jour. Votre coût dépend du modèle choisi, de la gestion des sessions et de la taille du codebase. C’est précisément la raison pour laquelle les leviers présentés ci-dessous sont importants.

Consulter sa propre utilisation

Dans Claude Code, la commande est /usage (/cost fonctionne toujours, c’est un alias). Le bloc Session en haut affiche les statistiques de tokens et une estimation calculée localement du coût de la session en cours. Avec les forfaits par abonnement, ce même écran affiche les barres de limite du forfait et ventile l’utilisation récente entre les skills, les sous-agents, les plugins et chaque serveur MCP. Pour connaître la facturation exacte des comptes API, consultez la page d’utilisation de la Claude Console, qui fait foi. La valeur affichée par l’interface de ligne de commande est une estimation. /context affiche une grille en couleurs de ce qui occupe la fenêtre de contexte, notamment le prompt système, les outils, les définitions MCP, les fichiers et l’historique. C’est le moyen le plus rapide de repérer un CLAUDE.md trop volumineux ou un serveur MCP trop bavard. Passez all pour afficher le détail complet de chaque élément.

Depuis l’API, chaque réponse indique exactement ce qui s’est produit :

response = client.messages.create(model="claude-sonnet-5", max_tokens=2048,
                                  messages=messages)
u = response.usage
total_prompt = u.input_tokens + u.cache_creation_input_tokens + u.cache_read_input_tokens
print(f"uncached={u.input_tokens} written={u.cache_creation_input_tokens} "
      f"read={u.cache_read_input_tokens} output={u.output_tokens}")

Notez que input_tokens correspond uniquement au reliquat non mis en cache. La taille réelle du prompt est la somme des trois champs d’entrée. Un agent qui a fonctionné pendant une heure et affiche input_tokens: 4000 n’est pas bon marché : les 200,000 autres tokens ont été servis depuis le cache. Pour effectuer une estimation avant l’envoi, utilisez le endpoint de comptage des tokens. Son appel est gratuit, il dispose de sa propre limite de débit et utilise le tokenizer du modèle que vous indiquez. Considérez le résultat comme une estimation proche : la facturation repose sur la requête réelle.

count = client.messages.count_tokens(model="claude-sonnet-5",
                                     messages=[{"role": "user", "content": big_file}])
print(count.input_tokens)

Ne faites jamais tiktoken, pour la raison indiquée ci-dessus.

Abonnements ou paiement à l’usage

Le fonctionnement décrit dans ce guide est identique partout ; seule la facturation diffère. Avec une clé API, Anthropic facture à l’usage, par token, aux tarifs publiés. Tous les montants indiqués plus haut correspondent donc à des dépenses réelles. La facturation commence plus tôt que beaucoup ne le pensent, car il n’existe pas de free tier sur lequel se rabattre. Vous disposez seulement d’un petit crédit à l’inscription et de quelques endpoints gratuits. Consultez ce qu’un nouveau compte API reçoit réellement avant d’enregistrer une carte bancaire. Avec un abonnement Claude (Pro, Max, Team, Enterprise), l’utilisation de Claude Code est prélevée sur le quota inclus dans votre offre. En juillet 2026, ce quota comprend une fenêtre glissante de cinq heures et une fenêtre hebdomadaire, partagées entre les modèles et avec les conversations de claude.ai. Le montant en dollars /usage est donc indicatif et ne correspond pas à une facture. Lorsque vous épuisez une fenêtre, le message « Vous avez atteint votre limite de session » ou « Vous avez atteint votre limite hebdomadaire » s’affiche avec l’heure de réinitialisation. Changer de modèle avec /model ne rétablit pas l’accès, car les fenêtres sont partagées entre les modèles. Ces fenêtres dépendent du compte, et non du client utilisé. Cela est utile à savoir si vous cherchez encore ce qui fonctionne nativement sous Linux et quelle offre couvre chaque interface. La fenêtre épuisée détermine la durée de l’attente et les actions utiles entre-temps. Il est donc préférable de connaître vos options lorsque vous atteignez une limite en cours de tâche. Les offres peuvent aussi activer des crédits d’utilisation, gérés avec /usage-credits, pour acheter de l’utilisation au-delà du quota. Je n’indique volontairement pas les quotas des offres : ce sont les valeurs les plus susceptibles de changer dans ce domaine. Consultez plutôt claude.com/pricing et vos propres /usage indicateurs. Le fonctionnement des tokens reste important avec un abonnement : une session inefficace consomme votre fenêtre exactement comme elle consommerait des dollars. Pour les abonnements, consultez quelle offre Claude correspond à votre utilisation.

Les leviers qui fonctionnent réellement

• Limitez ce que l’agent lit. « Corrigez le bug de validation dans auth.py » ne lit qu’un fichier ; « améliorez cette base de code » en lit quarante. Gardez CLAUDE.md concis : il est chargé à chaque session. Limitez-le à l’essentiel et placez les instructions propres au workflow dans des skills chargées à la demande.
• Soyez clair et concis. Entre deux tâches sans rapport, /clear est renvoyé et facturé à nouveau à chaque message suivant. Dans une même tâche longue, /compact Focus on the failing tests and the diff résume l’historique et vous évite de suivre une croissance quadratique.
• Adaptez la taille du modèle. Sonnet convient à la plupart des tâches de développement au tarif de $2/$10 par million de tokens, selon la tarification de lancement en juillet 2026 ($3/$15 au tarif catalogue, contre $5/$25 pour Opus). Haiku, à $1/$5, convient aux tâches mécaniques des sous-agents, comme le tri des journaux. Fable 5 se situe à l’autre extrémité, à $10/$50, soit deux fois le tarif d’Opus sur les deux tranches. Il est donc utile de savoir quelles tâches justifient réellement ce tarif avant de le laisser sélectionné pour les tâches courantes. /model permet de changer de modèle en cours de session.
• Préfiltrez les sorties verbeuses. Un hook qui réduit l’exécution des tests aux échecs avec grep avant que Claude ne la reçoive transforme 20,000 tokens de résultat d’outil en 300. Cette réduction s’applique à chaque nouvel envoi de ce tour.
• Regroupez les tâches non interactives. Pour vos propres pipelines API, la classification, les revues en volume et les tâches nocturnes, l’API Batches exécute les mêmes modèles avec une remise de 50 %, en échange d’un traitement asynchrone.
• Tenez compte de la durée de validité du cache. Travaillez par sessions continues. Une session Claude Code détachée dans tmux sur un VPS ne coûte rien lorsqu’elle est inactive : les tokens ne sont consommés que pendant l’exécution d’un tour. En revanche, l’inactivité fait perdre le cache actif, et le tour suivant doit réécrire le contexte.

FAQ

Combien de tokens une session de programmation dans Claude Code utilise-t-elle ?

Il n’existe pas de nombre fixe. Un tour en milieu de session contient souvent plusieurs dizaines de milliers de tokens de prompt lorsque les fichiers et l’historique se sont accumulés. Une session de travail atteint plusieurs millions de tokens, dont la plupart sont servis depuis le cache à un dixième du tarif de base. À titre de référence, les chiffres publiés par Anthropic pour les entreprises en juillet 2026 indiquent une moyenne d’environ $13 par développeur et par jour d’activité, avec 90% des utilisateurs sous $30. Exécutez /usage dans votre propre session. Cinq minutes de surveillance sont plus utiles que n’importe quelle moyenne publiée.

Les tokens de réflexion sont-ils facturés même lorsque je ne peux pas les voir ?

Oui. Les tokens de réflexion sont facturés comme des tokens de sortie, au tarif le plus élevé, et sont comptabilisés dans max_tokens. Les modèles actuels les facturent même lorsque l’interface n’affiche pas le résumé du raisonnement. Si une réponse s’interrompt avec stop_reason: "max_tokens" avant la fin de la réponse visible, la réflexion a probablement consommé le budget. Dans Claude Code, réduisez le niveau d’effort avec /effort pour les tâches qui ne nécessitent pas un raisonnement approfondi.

Pourquoi une longue session Claude Code devient-elle plus coûteuse à chaque message ?

Parce que l’API est sans état : à chaque tour, elle renvoie toute la conversation, chaque fichier lu, chaque résultat d’outil et chaque échange précédent comme tokens d’entrée facturés. Le tour 50 contient donc les tours 1 à 49. Le prompt caching sert le préfixe répété à environ un dixième du prix de base des entrées, mais ce préfixe continue de grossir. De plus, toute période d’inactivité dépassant le TTL du cache transforme le tour suivant en une nouvelle écriture facturée au tarif plein. /compact réduit l’historique. /clear le réinitialise.

Comment vérifier l’utilisation de mes tokens et mon coût Claude ?

Dans Claude Code, /usage affiche les statistiques de tokens de la session, une estimation locale du coût et les barres indiquant les limites du forfait pour les abonnements (/cost est un alias). /context indique ce qui remplit la fenêtre. Pour les données de facturation API officielles, utilisez la page d’utilisation dans la Claude Console. Dans votre propre code, lisez response.usage. La somme de input_tokens, cache_creation_input_tokens et cache_read_input_tokens donne la taille réelle du prompt. Pour faire une estimation à l’avance, utilisez le endpoint count_tokens, jamais tiktoken.