Par Prompt caching Claude : calcul du seuil de rentabilité
Avec une écriture à 1,25× et une lecture à 0,1×, le préfixe Claude devient rentable à la 2e utilisation. Vérifiez le calcul dans l’API.
Coût du prompt caching avant les économies
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 de base de l’entrée 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 évolue.
Il s’agit de payer un supplément maintenant pour bénéficier d’une remise 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 normal de l’entrée pour cette partie. Si un préfixe n’est jamais réutilisé pendant sa durée de vie, vous payez 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 pour 1.25B et les N moins 1 requêtes suivantes le lisent pour 0.1B. En égalant les deux coûts, vous obtenez 0.9N = 1.15, soit N = 1.28. La deuxième requête est déjà moins chère que l’absence totale de cache.
En répétant le calcul avec l’écriture à 2x du cache d’une heure, vous obtenez 0.9N = 1.9, soit N = 2.11. Le cache longue durée nécessite deux lectures pour 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 avec 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 facturé $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 requête seule 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 coûte $0.135, contre $0.20 sans cache. Le cache d’une heure reste plus cher à ce stade : $0.21, contre $0.20. Il devient moins cher que l’absence de cache à la troisième requête seulement : $0.22, contre $0.30. Avec 20 requêtes, l’écart est de $2.00, contre $0.315.
Un cache hit actualise également l’entrée. C’est pourquoi le tableau tarifaire publié appelle cette colonne « cache hits and refreshes ». Un endpoint très sollicité conserve donc une entrée de 5 minutes indéfiniment, au tarif des lectures. La durée de vie d’une heure ne justifie son écriture à 2x que lorsque votre trafic comporte de véritables intervalles sans requêtes.
Ce que coûte un faible taux de réussite
Les requêtes réelles produisent des échecs de cache. Une requête qui ne trouve pas son préfixe dans le cache, mais qui contient tout de même un breakpoint, est facturée comme une écriture. La manière correcte de modéliser ce coût consiste donc à le calculer en fonction du taux de réussite. Le graphique ci-dessous présente ce calcul pour 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 réussite de 0 %, vous payez $125.00 au lieu de $100.00, et le cache d’une durée de 1 heure double la facture, qui atteint $200.00. En résolvant 1.25 moins 1.15h = 1, on constate que le cache de 5 minutes commence à réduire le coût à partir d’un taux de réussite d’environ 22 %. C’est pourquoi un taux de 25 % atteint déjà $96.25. Le même calcul avec une écriture facturée 2x donne environ 53 % pour le cache d’une durée de 1 heure. Un taux de réussite de 50 % coûte donc encore $105.00, au-dessus de la ligne sans cache. À 90 %, les deux atteignent respectivement $21.50 et $29.00. À 99 %, le cache de courte durée atteint $11.15, une valeur proche du plancher correspondant à un dixième du prix sans cache.
Le taux de réussite 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 comporter 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 succès de 90 pour cent 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 nu de 2,000 tokens permet d’économiser $7.85 pour 1,000 requêtes par rapport au coût de $10.00 sans cache. À grande échelle, cela représente une somme réelle, mais ce n’est pas ce qui rend le caching intéressant. Ajoutez les tool definitions : vous atteignez 8,000 tokens et $31.40 d’économies. 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 : un contexte de codebase ou de transcript de 120,000 tokens coûte $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 avec le taux de succès, et avec rien d’autre. Cela change aussi ce qu’il vaut la peine d’inclure dans un prompt : ce que coûtent réellement un million de tokens Claude revient à un dixième du prix affiché pour tout contenu envoyé plus d’une fois.
À quoi cela ressemble sur une facture mensuelle
Le graphique ci-dessous prend le préfixe de tokens 8,000 présenté plus haut, ainsi qu’un system prompt et les définitions des outils, avec un taux de réussite 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 tokens d’entrée sans cache s’élève à $40,000.00, et le cache en supprime $31,400.00. Ces montants concernent uniquement les tokens d’entrée. La sortie est facturée séparément et le cache ne la réduit pas. Gardez-le à l’esprit avant de promettre une réduction de 90 % de la facture. Le cache complète les autres pratiques qui permettent de 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 dans la réponse. Chaque réponse de l’API Messages indique le nombre de tokens mis en cache, le nombre de tokens lus depuis le cache et le nombre de tokens frais à traiter.
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 une valeur non nulle pour cache_creation_input_tokens et une valeur nulle pour cache_read_input_tokens. Le deuxième appel inverse ces valeurs, car le préfixe a été trouvé. input_tokens compte uniquement les tokens situés après le dernier breakpoint. Lors d’un deuxième appel normal, ce nombre est donc faible. Il correspond généralement au nouveau message utilisateur.
Vous pouvez effectuer le même contrôle depuis le shell, avec un request body 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'Lors d’un deuxième appel normal, la sortie ressemble à 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 en échange.
Pour une durée de vie de 1 heure, le breakpoint contient une durée de vie (TTL) :
{
"type": "text",
"text": "your stable prefix",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}Il existe également une mise en cache automatique : un seul champ cache_control au niveau supérieur de la requête, après lequel l’API gère les breakpoints à mesure que la conversation s’allonge. Ce mécanisme utilise l’un de vos quatre emplacements de breakpoint. Commencez par cette option. Passez aux breakpoints explicites lorsque vous devez choisir exactement où placer la limite.
La règle d’ordre qui détruit les taux de succès
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. Modifier la description d’un outil invalide aussi le prompt système et tout l’historique des messages, même si vous n’y avez pas touché.
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 responsable habituel est un horodatage. Une ligne contenant Current time: 2026-08-03T14:07:11Z en haut d’un prompt système garantit un taux de succès 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 diffèrent selon les requêtes doivent eux aussi être placés après le bloc mis en cache. Sinon, ils repoussent chaque token 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 point de rupture. Si ce bloc est différent à chaque fois, aucun contenu stable n’est jamais enregistré. La recherche rétrospective ne trouve alors que les entrées écrites par les requêtes précédentes à leurs propres points de rupture mobiles. 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 contenu 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 cache.
Le préfixe minimal et l’absence d’effet silencieuse
Un préfixe plus court que le minimum du modèle n’est pas mis en cache, sans qu’aucune information ne vous l’indique. Il n’y a ni erreur ni avertissement. La requête réussit et les deux compteurs restent à 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 restent à 0 pour une requête que vous pensez mise en cache, vérifiez d’abord la longueur du préfixe. C’est également pourquoi le modèle le moins cher n’est pas automatiquement le moins cher pour une charge de travail utilisant la mise en cache. Haiku 4.5 nécessite un préfixe huit fois plus long qu’Opus 5 pour activer la mise en cache. Ainsi, un prompt système de 2,000 tokens est mis en cache avec l’un et ignoré silencieusement avec l’autre.
Ce que Claude Code met en cache pour vous, et ce qu’il ne peut pas mettre en cache
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 de position. 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 largement inférieur à ce que laisse penser la taille du contexte. Cela apparaît dans les compteurs décrits dans la manière dont Claude Code indique l’utilisation des tokens.
En revanche, cela ne fonctionne pas pour une modification effectuée près du début du contexte. L’historique de conversation est en ajout seulement. Les nouveaux tours prolongent donc un préfixe déjà mis en cache. Si vous modifiez un fichier 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 la règle du préfixe qui s’applique exactement comme prévu.
Si vous écrivez vous-même un client, appliquez cette organisation dès la première requête au lieu de l’ajouter après coup : construisez l’appel comme dans une première application Claude API sur un VPS, avec les blocs stables en premier et les blocs variables en dernier.
Modes d’échec et symptômes observables
Chaque appel est une écriture. cache_creation_input_tokens est différent de zéro sur chaque requête, tandis que cache_read_input_tokens reste à 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 à 0. Le préfixe est inférieur à la longueur minimale du modèle, ou le champ cache_control n’est jamais parvenu à l’API. Commencez par compter les tokens du préfixe, puis journalisez le corps de la requête réellement envoyé.
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. 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. Après chaque déploiement qui modifie le prompt, prévoyez une série coûteuse d’écritures.
La facture a augmenté après l’activation de la mise en cache. Votre taux de hits est inférieur au seuil de rentabilité. Avec le cache de 5 minutes, l’envoi du préfixe sans mise en cache coûte moins cher sous environ 22 percent. Avec le cache de 1 hour, c’est également le cas sous environ 53 percent.
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.25x le tarif d’entrée de base et une lecture coûte 0.1x. 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. Le cache de 1 heure facture les écritures 2x et atteint le seuil à N = 2.11. Il nécessite donc deux lectures.
Pourquoi cache_read_input_tokens vaut-il toujours zéro ?
Vérifiez d’abord la longueur du préfixe : en dessous du minimum du modèle, soit 512 tokens sur Claude Opus 5 et 4,096 sur Claude Haiku 4.5 en août 2026, la mise en cache est ignorée sans message et les deux compteurs restent à 0. Si le préfixe est assez long, recherchez du contenu qui change entre les appels et qui se trouve au niveau du point de coupure ou avant celui-ci, par exemple un timestamp 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 dépassait 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 que vous avez déjà envoyés, et le modèle reçoit 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 environ 53 %. L’écriture à 2x représente deux fois le surcoût de l’écriture à 1.25x en cas d’absence de succès. Une entrée de cache de 5 minutes est renouvelée à chaque succès. Un trafic régulier la maintient donc active au tarif des lectures, sans jamais payer pour une durée de vie plus longue.