Par Claude prompt caching : calcul du seuil de rentabilité
Avec une écriture à 1,25x et une lecture à 0,1x, le préfixe Claude devient rentable dès la deuxième utilisation. Vérifiez le calcul dans l’API.
Les coûts 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. La décision repose sur deux multiplicateurs appliqués au prix d'entrée de base du modèle. En octobre 2026, une écriture en 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 d'une heure, sur tous les modèles. Une lecture en cache coûte 0,1x sur la plupart des modèles, mais ce multiplicateur de lecture n'est plus uniforme. Il est de 0,025x sur Claude Fable 5.1 et Claude Mythos 5.1, lancés à ce tarif le 1er septembre 2026. Il est de 0,05x sur Claude Opus 5.5 et Claude Sonnet 5.5 ; le tarif de Sonnet 5.5 est passé de 0,1x à ce niveau le 7 octobre 2026. Les chiffres ci-dessous utilisent le taux de lecture standard de 0,1x. Les lectures moins coûteuses améliorent légèrement le seuil de rentabilité, et la section suivante détaille l'ampleur de cet avantage.
Le principe consiste à payer un surcoût immédiat pour obtenir une réduction ultérieure. Vous payez un supplément une seule fois pour stocker un préfixe. Chaque requête ultérieure commençant par exactement les mêmes octets paie alors un dixième du prix d'entrée normal pour cette partie, voire moins sur les modèles cités plus haut. Un préfixe qui n'est jamais réutilisé durant sa durée de vie vous a coûté 25 pour cent de plus pour rien.
Le seuil de rentabilité, en une ligne d'algèbre
Appelons B le coût de base de l'entrée du préfixe si vous l'envoyez sans mise en 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 autres requêtes le lisent à 0,1B. En égalisant les deux, on obtient 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.
Répétez l'opération avec l'écriture à 2x du cache d'une heure et vous obtenez 0,9N = 1,9, soit N = 2,11. Le cache long nécessite deux lectures avant d'atteindre le seuil de rentabilité, ce qui explique pourquoi il n'est pas le choix par défaut.
Sur des lectures moins coûteuses, la ligne bouge, mais peu. À une lecture de 0,05x, le cache de 5 minutes donne 0,95N = 1,2, soit N = 1,26, et à 0,025x, il donne 0,975N = 1,225, soit également N = 1,26. Le cache d'une heure descend à N = 2,05 et N = 2,03. La réponse pratique est la même pour chaque modèle : le cache de 5 minutes est rentable dès la deuxième requête, le cache d'une heure dès la troisième.
Le graphique ci-dessous calcule cela pour un préfixe de 20 000 tokens sur Claude Opus 5. Son tarif d'entrée de base est de 5 $ par million de tokens en octobre 2026, inchangé depuis août. Opus 5 est désormais un modèle legacy, bien qu'il soit toujours disponible. Son successeur, Claude Opus 5.5, est listé à 4 $ par million avec une lecture à 0,05x, donc le même préfixe y coûte 0,10 $ à l'écriture et 0,004 $ à la lecture. Appliquez un coefficient de 0,6 à chaque chiffre pour un modèle à 3 $ par million avec la lecture standard à 0,1x. La forme de la courbe ne change pas.
Les données de ce graphique
[
{
"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 isolée coûte $0.10 sans cache et $0.125 avec cache ; mettre en cache une requête unique est donc une perte sèche. Dès la deuxième requête, le cache de 5 minutes est à $0.135 contre $0.20. Le cache d'une heure est encore perdant à ce stade, à $0.21 contre le même $0.20, et il ne dépasse la ligne sans cache qu'à la troisième requête : $0.22 contre $0.30. À 20 requêtes, l'écart est de $2.00 contre $0.315.
Un cache hit rafraîchit également l'entrée, c'est pourquoi le tableau des prix publié nomme cette colonne cache hits and refreshes. Un endpoint actif maintient donc une entrée de 5 minutes en vie indéfiniment aux prix de lecture, et la durée de vie d'une heure ne justifie son écriture à 2x que lorsque votre trafic présente de réelles interruptions.
Le coût d'un faible taux de succès (hit rate)
Les requêtes réelles qui ne sont pas en cache échouent. Une requête qui manque le cache mais contient un point d'arrêt est facturée comme une écriture. La méthode honnête pour modéliser cela consiste à exprimer le coût en fonction du taux de succès. Le graphique ci-dessous illustre ce phénomène pour 1 000 requêtes, chacune comportant le même préfixe de 20 000 tokens.
Les données de ce graphique
[
{
"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 pour cent, vous payez $125.00 au lieu de $100.00, et le cache d'une heure double la facture à $200.00. En résolvant 1,25 moins 1,15h = 1, on constate que le cache de 5 minutes commence à être rentable à partir d'un taux de succès d'environ 22 pour cent, ce qui explique pourquoi le taux de 25 pour cent affiche déjà $96.25. Le même calcul appliqué à une écriture doublée donne environ 53 pour cent pour le cache d'une heure ; ainsi, un taux de succès de 50 pour cent coûte toujours $105.00, soit au-dessus de la ligne sans cache. À 90 pour cent, les deux valeurs atteignent $21.50 et $29.00. À 99 pour cent, le cache court atteint $11.15, proche du plancher d'un dixième du prix sans cache.
Sur un modèle avec une lecture à 0,05x, les seuils tombent à environ 21 pour cent pour le cache de 5 minutes et 51 pour cent pour le cache d'une heure. Avec une lecture à 0,025x, ils descendent à environ 20 et 51 pour cent. Le plancher diminue avec le prix de la lecture, pour atteindre un vingtième ou un quarantième du coût sans cache.
Le taux de succès est la métrique à instrumenter, car c'est la seule variable que vous contrôlez une fois la taille du préfixe fixée.
Quels préfixes justifient un point d'arrêt
Une requête peut comporter jusqu'à quatre points d'arrêt de cache ; la question est donc de savoir quels blocs en méritent un. Les candidats sont les blocs identiques octet par octet entre les appels et suffisamment volumineux pour être significatifs. Le tableau ci-dessous évalue quatre formes courantes sur 1 000 requêtes avec un taux de succès de 90 % sur le cache de 5 minutes.
Les données de ce graphique
[
{
"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 prompt système minimal de 2,000 tokens permet d'économiser $7.85 pour 1 000 requêtes, contre $10.00 sans cache. C'est une économie réelle en volume, mais ce n'est pas ce qui rend la mise en cache intéressante. Ajoutez les définitions d'outils et vous atteignez 8,000 tokens pour une économie de $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 modifie l'architecture : 120,000 tokens de base de code ou de contexte de 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, le taux de succès, et rien d'autre. Cela change ce qui vaut la peine d'être inclus dans un prompt : ce que coûte réellement un million de tokens Claude tombe à un dixième du prix affiché, voire moins sur les modèles avec des lectures moins coûteuses, pour tout ce que vous envoyez 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.
Les données de ce graphique
[
{
"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 détruit les taux de cache
Le cache fait correspondre un préfixe octet par octet depuis le début de la requête, et la requête est assemblée dans un ordre fixe : les tools, puis le system, puis les messages. Une modification à n'importe quel niveau invalide ce niveau et tout ce qui suit. Modifiez une description de tool et le system prompt ainsi que l'historique complet des messages sont invalidés avec elle, même si vous n'y avez pas touché.
Cela donne une règle sans exception. Tout ce qui change entre deux appels doit être placé après tout ce qui ne change pas.
Le coupable habituel est l'horodatage. Une ligne contenant Current time: 2026-08-03T14:07:11Z au début d'un system prompt garantit un taux de succès de 0 pour cent, car le hash du préfixe est différent à chaque appel et aucune entrée précédente ne peut jamais correspondre. Déplacez-le dans le message utilisateur, à la fin. Un identifiant de session ou un nonce par requête casse les choses de la même manière et nécessite la même correction. Les documents récupérés qui diffèrent 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 second coupable est de placer le point de rupture sur le bloc qui change. Les écritures en cache se produisent au point de rupture ; donc si ce bloc est différent à chaque fois, rien de stable n'est jamais stocké, et la recherche ne trouve que les entrées que les requêtes précédentes ont écrites à leurs propres points de rupture mobiles. Placez cache_control sur le dernier bloc dont le contenu est identique pour toutes les requêtes.
Le troisième est un changement de paramètre auquel vous n'avez pas pensé en tant que contenu de prompt. Un modèle différent possède un cache différent. Changer tool_choice invalide l'historique des messages, bien que les tools et le system prompt restent en cache. Ajouter ou supprimer un tool invalide tout le reste.
Le préfixe minimal et l'absence silencieuse d'opération
Un préfixe plus court que le minimum requis par le modèle n'est pas mis en cache, sans aucun avertissement. Il n'y a ni erreur, ni notification. La requête aboutit et les deux compteurs affichent 0. En octobre 2026, les minimums publiés sont les suivants :
- 512 tokens pour Claude Opus 5 et Claude Fable 5, ainsi que pour les versions plus récentes Opus 5.5, Sonnet 5.5, Fable 5.1 et Haiku 5.5
- 1 024 tokens pour Claude Sonnet 5 et Claude Opus 4.8
- 4 096 tokens pour Claude Haiku 4.5
Si les deux compteurs affichent 0 sur une requête que vous pensez être en cache, vérifiez la longueur du préfixe avant toute autre chose. C'est aussi la raison pour laquelle le modèle le moins cher n'est pas automatiquement le plus économique pour une charge de travail utilisant le cache. Haiku 4.5 nécessite un préfixe huit fois plus long qu'Opus 5 pour que la mise en cache s'active. Ainsi, un prompt système de 2 000 tokens est mis en cache sur l'un et ignoré silencieusement sur l'autre.
Où Claude Code met en cache pour vous, et où il ne le peut pas
Claude Code met en cache son propre préfixe. Le system prompt et les définitions d'outils sont placés au début de chaque requête et ne bougent pas ; ils sont donc écrits une fois et relus pour le reste de la session. C'est pourquoi le coût par tour d'une longue session est bien inférieur à ce que suggère la taille du contexte, et cela apparaît dans les compteurs décrits dans comment Claude Code rapporte l'utilisation des jetons.
Là où il ne peut pas vous aider, c'est lors d'un changement près du début du contexte. L'historique de la conversation est en ajout seul (append-only), donc les nouveaux tours ordinaires étendent un préfixe déjà mis en cache. Modifier un fichier qui a été lu au début de la session ne rompt pas cela, car Claude Code ajoute une note indiquant que le fichier a changé plutôt que de réécrire la lecture précédente. Ce qui rompt le cache, c'est le changement de modèle, car chaque modèle possède son propre cache. Connecter un serveur MCP dont les outils se chargent dans le préfixe le rompt également, tout comme la compaction de la conversation. Chacune de ces actions force le tour suivant à réécrire le préfixe. Une longue période d'inactivité produit le même effet, car l'entrée expire et le tour suivant paie une écriture complète. Rien de tout cela n'est un bug. C'est la règle du préfixe qui fonctionne exactement comme prévu.
Si vous développez votre propre client, appliquez la structure dès la première requête plutôt que de l'adapter après coup : construisez l'appel comme le fait une première application API Claude sur un VPS, avec les blocs stables en premier et les blocs volatils à la fin.
Modes de défaillance et symptômes observés
Chaque appel est une écriture. cache_creation_input_tokens est non nul à chaque requête alors que cache_read_input_tokens reste à 0. Quelque chose au niveau ou avant le point d'arrêt change entre les appels. Affichez les 200 premiers caractères de votre préfixe assemblé sur deux requêtes consécutives et comparez-les visuellement.
Les deux compteurs sont à 0. Le préfixe est inférieur au minimum requis par le modèle, ou le champ cache_control n'a jamais atteint l'API. Comptez d'abord les jetons du préfixe, puis journalisez le corps de la requête que vous avez réellement envoyé.
Les lectures fonctionnent, puis s'arrêtent. Une série de succès, puis une écriture, puis à nouveau des succès. L'intervalle entre les requêtes était plus long que la durée de vie. Acceptez l'écriture ou passez au TTL de 1 heure une fois que vous avez vérifié que votre taux de succès dépasse 53 pour cent, ou environ 51 pour cent sur un modèle avec une lecture à 0.05x ou 0.025x.
Le taux de succès chute après un déploiement. Une description d'outil a été modifiée ou un modèle a été changé. Les deux invalident l'intégralité du préfixe. Attendez-vous à une série d'écritures coûteuses après chaque déploiement touchant le prompt.
La facture a augmenté après l'activation de la mise en cache. Votre taux de succès est inférieur au seuil de rentabilité. En dessous d'environ 22 pour cent pour le cache de 5 minutes, envoyer le préfixe sans cache est moins coûteux ; il en va de même en dessous d'environ 53 pour cent pour le cache de 1 heure. Sur les modèles avec des lectures moins coûteuses, ces seuils se situent autour de 20 à 21 pour cent et 51 pour cent.
FAQ
Combien de fois un prompt doit-il être réutilisé pour 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 l'entrée de base et une lecture coûte 0,1 fois ce prix sur la plupart des modèles. Ainsi, N requêtes sans cache coûtent 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, donc la deuxième requête est déjà rentable. Sur les modèles avec une lecture à 0,05 ou 0,025 fois le prix, le croisement se situe à N = 1,26, ce qui donne le même résultat. Le cache d'une heure écrit à 2 fois le prix et se rentabilise à N = 2,11, ou environ 2,05 sur les lectures moins chères ; il nécessite donc deux lectures.
Pourquoi cache_read_input_tokens est-il toujours à zéro ?
Vérifiez d'abord la longueur du préfixe : en dessous du minimum requis par le modèle, soit 512 jetons sur Claude Opus 5 et 4 096 sur Claude Haiku 4.5 en octobre 2026, la mise en cache est ignorée silencieusement et les deux compteurs affichent 0. Si le préfixe est suffisamment long, recherchez un contenu qui change entre les appels, situé au niveau ou avant le point de rupture, comme un horodatage ou un identifiant de session dans le prompt système. Si les compteurs fonctionnaient et 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 jetons 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é liée à la facturation et à la latence, et non d'un changement de comportement. Cela signifie également que vous pouvez l'activer sur un prompt fonctionnel sans avoir à relancer vos évaluations.
Dois-je payer pour le cache d'une heure ?
Uniquement si votre trafic présente des interruptions supérieures à 5 minutes et que votre taux de succès permet d'atteindre environ 53 pour cent, ou environ 51 pour cent sur un modèle avec une lecture moins chère. En cas d'échec, l'écriture à 2 fois le prix coûte quatre fois plus cher que l'écriture à 1,25 fois. Une écriture manquée d'une heure gaspille la totalité du prix de l'entrée de base du préfixe, alors qu'une écriture manquée de 5 minutes n'en gaspille qu'un quart. Une entrée de 5 minutes est rafraîchie à chaque succès ; un trafic régulier la maintient donc active au prix de la lecture sans jamais payer pour la durée de vie plus longue.