Par Claude prompt caching : calcul du seuil de rentabilité
L’écriture coûte 1,25 fois le tarif d’entrée et la lecture 0,1 fois. Calculez quand le cache devient rentable, puis vérifiez-le dans l’API Claude.
Ce que coûte le prompt caching avant de devenir rentable
Le prompt caching permet à Claude de réutiliser le début de votre prompt au lieu de le relire à chaque appel. Toute la décision repose sur deux multiplicateurs appliqués au prix de base des tokens d’entrée du modèle. En août 2026, l’écriture dans le cache coûte 1.25x le prix d’entrée de base pour une durée de vie de 5 minutes, ou 2x pour une durée de vie de 1 heure. La lecture depuis le cache coûte 0.1x. Ces multiplicateurs sont identiques pour tous les modèles. Le seuil de rentabilité ci-dessous ne change donc pas lorsque le prix par token varie.
Le principe est de payer un supplément maintenant pour bénéficier d’une réduction plus tard. Vous payez une fois de plus pour stocker un préfixe. Chaque requête suivante qui commence par exactement les mêmes octets paie alors un dixième du prix d’entrée normal pour cette partie. Un préfixe qui n’est jamais réutilisé pendant sa durée de vie vous coûte 25 pour cent de plus sans aucun avantage.
Le seuil de rentabilité, en une ligne d’algèbre
Appelez B le coût d’entrée de base du préfixe si vous l’envoyez sans cache. Sans cache, N requêtes coûtent N fois B. Avec le cache de 5 minutes, la première requête écrit le préfixe à 1.25B et les N moins 1 requêtes suivantes le lisent à 0.1B. En égalant les deux coûts, on obtient 0.9N = 1.15, soit N = 1.28. La deuxième requête coûte déjà moins cher que l’absence totale de cache.
En répétant le calcul avec l’écriture 2x du cache d’1 heure, on obtient 0.9N = 1.9, soit N = 2.11. Le cache longue durée nécessite deux lectures avant d’atteindre le seuil de rentabilité. C’est pourquoi il n’est pas le choix par défaut.
Le graphique ci-dessous calcule ces coûts pour un préfixe de 20,000 tokens sur Claude Opus 5, dont le tarif d’entrée de base est de $5 par million de tokens en août 2026. Multipliez chaque valeur par 0.6 pour un modèle à $3 par million. La forme de la courbe ne change pas.
The data behind this chart
[
{
"requests": 1,
"uncached_usd": "0.10",
"cached_5m_usd": "0.125",
"cached_1h_usd": "0.20"
},
{
"requests": 2,
"uncached_usd": "0.20",
"cached_5m_usd": "0.135",
"cached_1h_usd": "0.21"
},
{
"requests": 3,
"uncached_usd": "0.30",
"cached_5m_usd": "0.145",
"cached_1h_usd": "0.22"
},
{
"requests": 5,
"uncached_usd": "0.50",
"cached_5m_usd": "0.165",
"cached_1h_usd": "0.24"
},
{
"requests": 10,
"uncached_usd": "1.00",
"cached_5m_usd": "0.215",
"cached_1h_usd": "0.29"
},
{
"requests": 20,
"uncached_usd": "2.00",
"cached_5m_usd": "0.315",
"cached_1h_usd": "0.39"
}
]Une seule requête coûte $0.10 sans cache et $0.125 avec cache. Mettre en cache un prompt utilisé une seule fois représente donc une perte nette. À la deuxième requête, le cache de 5 minutes revient à $0.135, contre $0.20 sans cache. Le cache d’1 heure reste alors plus cher, à $0.21, contre les mêmes $0.20. Il devient moins cher que l’absence de cache à la troisième requête seulement : $0.22, contre $0.30. À 20 requêtes, l’écart est de $2.00 sans cache, contre $0.315 avec le cache de 5 minutes.
Un cache hit actualise également l’entrée. C’est pourquoi le tableau tarifaire publié intitule cette colonne « cache hits et actualisations ». Un endpoint très sollicité maintient donc une entrée de 5 minutes active indéfiniment, au tarif des lectures. La durée de vie d’1 heure ne justifie son écriture 2x que lorsque le trafic comporte de véritables intervalles.
Ce que coûte un faible taux de succès
Les requêtes réelles produisent des défauts de cache. Une requête qui ne trouve pas l’entrée en cache, mais qui contient toujours un breakpoint, est facturée comme une écriture. La bonne méthode consiste donc à modéliser le coût en fonction du taux de succès. Le graphique ci-dessous porte sur 1,000 requêtes contenant chacune le même préfixe de 20,000 tokens.
The data behind this chart
[
{
"hit_rate_percent": 0,
"cost_5m_usd": "125.00",
"cost_1h_usd": "200.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 25,
"cost_5m_usd": "96.25",
"cost_1h_usd": "152.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 50,
"cost_5m_usd": "67.50",
"cost_1h_usd": "105.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 75,
"cost_5m_usd": "38.75",
"cost_1h_usd": "57.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 90,
"cost_5m_usd": "21.50",
"cost_1h_usd": "29.00",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 95,
"cost_5m_usd": "15.75",
"cost_1h_usd": "19.50",
"uncached_usd": "100.00"
},
{
"hit_rate_percent": 99,
"cost_5m_usd": "11.15",
"cost_1h_usd": "11.90",
"uncached_usd": "100.00"
}
]Avec un taux de succès de 0 %, vous payez $125.00 au lieu de $100.00, et le cache de 1 heure double la facture, qui atteint $200.00. Résolvez 1.25 moins 1.15h = 1 : le cache de 5 minutes commence à faire économiser de l’argent avec un taux de succès d’environ 22 %. C’est pourquoi 25 % donnent déjà $96.25. Le même calcul avec l’écriture multipliée par 2 donne environ 53 % pour le cache de 1 heure. Un taux de succès de 50 % coûte donc encore $105.00, soit davantage que sans cache. À 90 %, les deux atteignent respectivement $21.50 et $29.00. À 99 %, le cache court atteint $11.15, une valeur proche du plancher fixé à un dixième du prix sans cache.
Le taux de succès est la valeur à instrumenter, car c’est le seul paramètre que vous contrôlez une fois la taille du préfixe fixée.
Quels préfixes méritent un breakpoint
Une requête peut contenir jusqu’à quatre breakpoints de cache. La question est donc de savoir quels blocs en méritent un. Les candidats sont les blocs identiques octet par octet d’un appel à l’autre et suffisamment volumineux pour avoir un impact. Le graphique ci-dessous compare quatre structures courantes sur 1,000 requêtes, avec un taux de hit de 90 % sur le cache de 5 minutes.
The data behind this chart
[
{
"label": "System prompt",
"prefix_size_tokens": "2,000",
"uncached_usd": "10.00",
"cached_usd": "2.15",
"saved_usd": "7.85"
},
{
"label": "System plus tools",
"prefix_size_tokens": "8,000",
"uncached_usd": "40.00",
"cached_usd": "8.60",
"saved_usd": "31.40"
},
{
"label": "Policy document",
"prefix_size_tokens": "25,000",
"uncached_usd": "125.00",
"cached_usd": "26.88",
"saved_usd": "98.12"
},
{
"label": "Codebase context",
"prefix_size_tokens": "120,000",
"uncached_usd": "600.00",
"cached_usd": "129.00",
"saved_usd": "471.00"
}
]Un system prompt minimal de 2,000 tokens permet d’économiser $7.85 par tranche de 1,000 requêtes, par rapport à $10.00 sans cache. À grande échelle, la somme est significative, mais ce n’est pas ce qui rend le caching intéressant. Ajoutez les définitions des outils : vous atteignez 8,000 tokens et économisez $31.40. Un document de politique de 25,000 tokens, sur lequel chaque requête pose des questions, permet d’économiser $98.12. La dernière ligne est celle qui change l’architecture : 120,000 tokens de contexte provenant d’une base de code ou d’une transcription coûtent $600.00 sans cache et $129.00 avec cache, soit une économie de $471.00.
Les économies augmentent avec la taille du préfixe et le taux de hit, et avec rien d’autre. Cela change les éléments qu’il est pertinent d’inclure dans un prompt : ce que coûtent réellement un million de tokens Claude revient au dixième du prix affiché pour tout contenu envoyé plus d’une fois.
À quoi cela ressemble sur une facture mensuelle
Le graphique ci-dessous utilise le préfixe de jetons 8,000 présenté plus haut, ainsi qu’un prompt système et des définitions d’outils, avec un taux de réutilisation de 90 %, puis l’extrapole à des volumes mensuels de requêtes.
The data behind this chart
[
{
"label": "10k requests",
"uncached_usd": "400.00",
"cached_usd": "86.00",
"saved_usd": "314.00"
},
{
"label": "100k requests",
"uncached_usd": "4,000.00",
"cached_usd": "860.00",
"saved_usd": "3,140.00"
},
{
"label": "1M requests",
"uncached_usd": "40,000.00",
"cached_usd": "8,600.00",
"saved_usd": "31,400.00"
}
]Avec 10,000 requêtes par mois, l’économie est de $314.00, soit la différence entre $400.00 et $86.00. Avec 100,000 requêtes, elle atteint $3,140.00. Avec un million de requêtes, la facture des entrées sans cache s’élève à $40,000.00, et le cache en supprime $31,400.00. Ces montants concernent uniquement les jetons d’entrée. La sortie est facturée séparément et le cache ne change rien à son coût. Gardez-le à l’esprit avant de promettre une réduction de 90 % de la facture. Le cache s’inscrit dans les pratiques plus générales décrites dans maîtriser la facture d’un agent IA sur un VPS.
Comment vérifier que le cache fonctionne
Ne vous fiez pas à la conception. Consultez le bloc d’utilisation de la réponse. Chaque réponse de l’API Messages (interface de programmation applicative) indique le nombre de tokens mis en cache, lus depuis le cache et traités comme nouveaux.
from anthropic import Anthropic
client = Anthropic()
resp = client.messages.create(
model="claude-opus-5",
max_tokens=512,
system=[
{
"type": "text",
"text": POLICY_DOCUMENT,
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": question}],
)
u = resp.usage
print("write:", u.cache_creation_input_tokens)
print("read: ", u.cache_read_input_tokens)
print("fresh:", u.input_tokens)Exécutez la requête deux fois avec le même document et une question différente. Le premier appel indique un cache_creation_input_tokens non nul et un cache_read_input_tokens nul. Le second inverse ces valeurs, car le préfixe a été trouvé. input_tokens ne compte que les tokens situés après le dernier point de mise en cache. Lors d’un second appel normal, cette valeur est donc faible et correspond généralement au nouveau message utilisateur. Les deux appels sont facturés, car l’API Claude ne propose aucun niveau gratuit, même si, pour un préfixe de 20,000 tokens au tarif indiqué plus haut, l’ensemble revient à environ quatorze centimes.
La même vérification depuis le shell, avec un corps de requête enregistré dans request.json :
curl -s https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d @request.json | jq '.usage'Un second appel normal affiche quelque chose comme ceci :
{
"input_tokens": 42,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 20143,
"output_tokens": 187
}Une seule ligne vous donne la réponse. Si cache_read_input_tokens reste à 0 d’un appel à l’autre, vous payez l’écriture à 1.25x à chaque fois sans rien récupérer du cache.
Pour une durée de conservation de 1 heure, le point de mise en cache contient une durée de vie (TTL) :
{
"type": "text",
"text": "your stable prefix",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}La mise en cache automatique est également disponible : un seul champ cache_control au niveau supérieur de la requête, après quoi l’API gère les points de mise en cache au fur et à mesure que la conversation s’allonge. Ce mécanisme utilise l’un de vos quatre emplacements de point de mise en cache. Commencez par cette méthode. Utilisez ensuite des points de mise en cache explicites lorsque vous devez choisir précisément l’emplacement de la limite.
La règle d’ordre qui fait chuter les taux de hit
Le cache compare un préfixe octet par octet depuis le début de la requête. La requête est assemblée dans un ordre fixe : outils, puis système, puis messages. Une modification à un niveau invalide ce niveau et tout ce qui le suit. Modifiez la description d’un outil : le prompt système et tout l’historique des messages sont invalidés avec elle, même si vous ne les avez pas modifiés.
Cela donne une règle sans exception. Tout ce qui change entre les appels doit venir après tout ce qui ne change pas.
Le principal responsable est généralement un horodatage. Une ligne contenant Current time: 2026-08-03T14:07:11Z en tête du prompt système garantit un taux de hit de 0 %, car le hash du préfixe est différent à chaque appel et aucune entrée précédente ne peut jamais correspondre. Déplacez cette ligne dans le message utilisateur, à la fin. Un identifiant de session ou un nonce propre à chaque requête provoque le même problème et se corrige de la même manière. Les documents récupérés qui varient selon la requête doivent également être placés après le bloc mis en cache. Sinon, ils repoussent chaque jeton stable derrière une limite qui se déplace.
Le deuxième problème consiste à placer le point de rupture sur le bloc qui change. Les écritures dans le cache ont lieu au niveau du point de rupture. Si ce bloc est différent à chaque fois, rien de stable n’est jamais stocké, et la recherche rétrospective ne trouve que les entrées écrites par les requêtes précédentes à leurs propres points de rupture variables. Placez cache_control sur le dernier bloc dont le contenu est identique d’une requête à l’autre.
Le troisième problème est une modification de paramètre que vous ne considérez pas comme faisant partie du prompt. Un modèle différent utilise un cache différent. Modifier le choix de l’outil invalide le cache à partir du niveau système. Ajouter ou supprimer un outil invalide tout le contenu.
Le préfixe minimal et l’absence silencieuse d’effet
Un préfixe plus court que le minimum du modèle n’est pas mis en cache, et rien ne vous l’indique. Il n’y a ni erreur ni avertissement. La requête aboutit et les deux compteurs affichent 0. En août 2026, les minimums publiés sont les suivants :
- 512 tokens sur Claude Opus 5 et Claude Fable 5
- 1,024 tokens sur Claude Sonnet 5 et Claude Opus 4.8
- 4,096 tokens sur Claude Haiku 4.5
Si les deux compteurs affichent 0 pour une requête que vous pensez mise en cache, vérifiez d’abord la longueur du préfixe. C’est aussi pourquoi le modèle le moins cher n’est pas automatiquement le moins coûteux pour une charge de travail utilisant le cache. Haiku 4.5 a besoin d’un préfixe huit fois plus long que celui d’Opus 5 pour activer la mise en cache. Ainsi, un prompt système de 2,000 tokens est mis en cache avec l’un, mais ignoré silencieusement avec l’autre.
Où Claude Code met en cache les éléments précédents, et où cela ne peut pas vous aider
Claude Code met en cache son propre préfixe. Le system prompt et les définitions des outils se trouvent au début de chaque requête et ne changent pas. Ils sont donc écrits une seule fois, puis relus pendant le reste de la session. C’est pourquoi le coût par tour d’une longue session est bien inférieur à ce que laisse penser la taille du contexte. Cela apparaît dans les compteurs décrits dans la façon dont Claude Code indique l’utilisation des tokens.
Le cache ne peut pas vous aider lorsqu’une modification intervient près du début du contexte. L’historique des conversations est en ajout uniquement. Chaque nouveau tour prolonge donc un préfixe déjà mis en cache. Si vous modifiez un fichier qui a été lu au début de la session, son contenu change au milieu de ce préfixe. Tous les tokens qui suivent la modification doivent alors être écrits de nouveau. Une longue période d’inactivité produit le même effet, car l’entrée expire et le tour suivant doit effectuer une écriture complète. Ce n’est pas un bug. Dans les deux cas, c’est le fonctionnement normal de la règle du préfixe.
Si vous écrivez votre propre client, appliquez cette organisation dès la première requête au lieu de la mettre en place après coup. Construisez l’appel comme dans une première application Claude API sur un VPS, en plaçant d’abord les blocs stables et les blocs volatils en dernier.
Modes d’échec et symptômes observés
Chaque appel est une écriture. cache_creation_input_tokens est différent de zéro à chaque requête, tandis que cache_read_input_tokens reste égal à 0. Un élément situé au niveau du point d’arrêt ou avant celui-ci change entre les appels. Affichez les 200 premiers caractères du préfixe assemblé lors de deux requêtes consécutives, puis comparez-les visuellement.
Les deux compteurs sont égaux à 0. Le préfixe est inférieur à la longueur minimale exigée par le modèle, ou le champ cache_control n’a jamais été transmis à l’API. Commencez par compter les tokens du préfixe, puis journalisez le corps de la requête réellement envoyée.
Les lectures fonctionnent, puis s’arrêtent. Une série de hits est suivie d’une écriture, puis de nouveaux hits. L’intervalle entre les requêtes était supérieur à la durée de vie du cache. Acceptez l’écriture, ou passez au TTL de 1 hour après avoir vérifié que votre taux de hits dépasse 53 percent.
Le taux de hits baisse après un déploiement. La description d’un outil a été modifiée ou le modèle a changé. Ces deux changements invalident l’intégralité du préfixe. Prévoyez une série coûteuse d’écritures après chaque déploiement qui modifie le prompt.
La facture a augmenté après l’activation de la mise en cache. Votre taux de hits est inférieur au seuil de rentabilité. En dessous d’environ 22 percent avec le cache de 5 minutes, l’envoi du préfixe sans cache coûte moins cher. En dessous d’environ 53 percent, il en va de même avec le cache de 1 hour.
FAQ
Combien de fois faut-il réutiliser un prompt avant que la mise en cache soit rentable ?
Une seule fois avec le cache de 5 minutes. Une écriture coûte 1.25 fois le prix de base des entrées et une lecture coûte 0.1 fois ce prix. N requêtes sans cache coûtent donc N, tandis que N requêtes avec cache coûtent 1.25 plus 0.1 fois N moins 1. Les deux courbes se croisent à N = 1.28. La deuxième requête est donc déjà rentable. Avec le cache de 1 heure, l’écriture coûte 2 fois le prix de base et le seuil est atteint à N = 2.11. Il faut donc deux lectures.
Pourquoi cache_read_input_tokens vaut-il toujours 0 ?
Vérifiez d’abord la longueur du préfixe. En dessous du minimum du modèle, soit 512 tokens pour Claude Opus 5 et 4,096 pour Claude Haiku 4.5 en août 2026, la mise en cache est ignorée silencieusement et les deux compteurs restent à 0. Si le préfixe est assez long, recherchez le contenu qui change entre les appels et qui se trouve au niveau du point de rupture ou avant celui-ci, par exemple un horodatage ou un identifiant de session dans le system prompt. Si les compteurs fonctionnaient auparavant puis se sont arrêtés, l’intervalle entre les requêtes était supérieur à la durée de vie du cache.
La mise en cache des prompts modifie-t-elle les réponses de Claude ?
Non. Le cache stocke la forme traitée des tokens déjà envoyés. Le modèle reçoit donc le même prompt dans les deux cas. Il s’agit d’une fonctionnalité de facturation et de latence, pas d’une modification du comportement. Vous pouvez donc l’activer sur un prompt fonctionnel sans relancer vos évaluations.
Dois-je payer pour le cache de 1 heure ?
Uniquement si votre trafic comporte des intervalles de plus de 5 minutes et si votre taux de succès dépassera encore environ 53 %. L’écriture à 2 fois le prix de base représente deux fois le surcoût de l’écriture à 1.25 fois ce prix lorsque le cache n’est pas utilisé. Une entrée du cache de 5 minutes est actualisée à chaque succès. Un trafic régulier la maintient donc active au prix des lectures, sans jamais payer pour une durée de vie plus longue.