La mécanique du cache, les paliers tarifaires, les durées de TTL et les seuils minimaux de tokens changent à mesure qu'Anthropic met à jour la plateforme. Ne vous fiez à aucun chiffre précis issu de guides tiers. Consultez toujours la documentation officielle du cache de prompt et la page Modèles et tarification pour les valeurs actuelles.
L'économie du cache de prompt
Chaque fois que vous appelez l'API de Claude, vous payez pour chaque token d'entrée que vous envoyez — y compris votre prompt système, vos définitions d'outils et tout contexte que vous injectez. Si vous effectuez de nombreux appels avec le même grand préfixe, vous payez pour traiter ce préfixe à partir de zéro à chaque fois.
Le cache de prompt change cela. Vous marquez une portion stable de votre prompt comme pouvant être mise en cache. Le premier appel la traite et la stocke. Les appels suivants qui atteignent le cache sautent ce traitement — et paient une fraction du tarif normal pour ces tokens.
Les économies ne sont pas cosmétiques. Pour les applications avec de grands prompts système stables ou un contexte lourd, le cache peut faire passer l'économie d'une fonctionnalité de « trop cher à expédier » à « pratiquement gratuit à faire tourner ».
Le modèle mental : préfixe stable, suffixe volatil
Voyez chaque appel d'API comme deux parties :
Le préfixe stable — le contenu qui ne change pas d'un appel à l'autre. C'est là que le cache s'applique. Exemples :
- Votre prompt système
- Les définitions d'outils
- Un grand document de référence ou une base de code que vous injectez à chaque appel
- Un long bloc d'exemples few-shot
Le suffixe volatil — le contenu qui change à chaque appel. C'est là que le cache ne s'applique pas. Exemples :
- Le message utilisateur actuel
- Les données en temps réel que vous injectez par requête
- L'historique de conversation qui grandit à chaque tour
La règle est simple : structurez vos prompts de sorte que le contenu stable vienne en premier, et le contenu changeant en dernier. Les points de rupture de cache sont positionnels — tout ce qui précède le point de rupture marqué est éligible au cache ; tout ce qui suit ne l'est pas.
Si vous placez du contenu dynamique avant du contenu statique, vous cassez le cache, car le préfixe change à chaque requête.
Comment fonctionne le modèle de coût
Le cache de prompt introduit une répartition en trois volets dans la tarification des tokens d'entrée :
| Type de token | Quand cela se produit | Coût relatif à une entrée normale |
|---|---|---|
| Écriture en cache | Premier appel, ou après expiration du cache | Plus élevé qu'une entrée normale |
| Lecture en cache | Appels suivants qui atteignent le cache | Bien plus bas qu'une entrée normale |
| Entrée régulière | Tokens après le dernier point de rupture de cache | Tarif normal |
Les multiplicateurs exacts figurent sur la page de tarification officielle et fluctuent — vérifiez-les directement. Ce qui ne change pas, c'est la structure : les écritures coûtent plus que la normale, les lectures coûtent bien moins. Le point de bascule — quand vous avez effectué assez d'appels en cache pour amortir le surcoût d'écriture — arrive vite sur tout prompt comportant un contenu stable substantiel.
La latence suit le même schéma. Les lectures en cache sautent le traitement complet de la portion mise en cache, ce qui réduit significativement le temps jusqu'au premier token sur les appels avec de grands préfixes.
Quand le cache de prompt aide
Le cache est rentable quand deux conditions sont réunies :
- Vous avez un préfixe stable substantiel (il existe un seuil minimal de tokens en dessous duquel le cache n'est pas disponible — consultez la documentation actuelle pour le chiffre exact par modèle).
- Vous réutilisez ce préfixe assez fréquemment pour atteindre le cache plus qu'occasionnellement.
Scénarios où le cache s'impose naturellement :
- Questions-réponses sur document — le même grand document est injecté pour de nombreuses questions d'utilisateurs.
- Assistants de code — une grande base de code ou arborescence de fichiers est incluse dans chaque requête.
- Boucles agentiques — le même prompt système et les mêmes définitions d'outils sont envoyés à chaque étape d'un flux de travail multi-étapes.
- Agents conversationnels à instructions longues — une persona détaillée, un jeu de règles ou une base de connaissances qui ne change jamais d'un appel à l'autre.
- Traitement par lots — de nombreuses entrées exécutées contre le même modèle de prompt.
Quand le cache de prompt n'aide pas
Le cache n'est pas utile quand :
- Vos prompts sont courts (en dessous du seuil minimal de tokens cacheables).
- Votre préfixe change à chaque appel — injecter un horodatage, un contexte spécifique à l'utilisateur, ou toute personnalisation dans la partie « stable » invalide le cache.
- Vous effectuez des appels peu fréquents avec de longs intervalles entre eux. Le contenu mis en cache expire après un TTL (une durée que vous pouvez configurer, dans les limites prises en charge par l'API). Si votre trafic est clairsemé, vous paierez surtout des coûts d'écriture avec peu de lectures.
- Votre préfixe est petit par rapport au contenu dynamique de chaque appel. Les économies évoluent avec la taille de ce qui est mis en cache.
Structurer les prompts pour qu'ils soient compatibles avec le cache
La seule exigence structurelle est l'ordre : le contenu stable doit venir avant le contenu volatil.
En pratique :
[Prompt système — instructions, persona, règles]
[Définitions d'outils — si statiques]
[Grands documents ou contexte injectés — s'ils sont les mêmes d'un appel à l'autre]
--------- point de rupture de cache ici ---------
[Contenu dynamique par appel — message utilisateur, extraits récupérés spécifiques à cette requête]
Vous marquez le point de rupture avec un champ cache_control sur le dernier bloc que vous voulez inclure dans le cache. Tout ce qui précède ce marqueur est éligible au cache ; tout ce qui suit est une entrée régulière.
Vous pouvez placer jusqu'à quatre points de rupture explicites dans une seule requête. C'est utile quand différentes parties de votre prompt changent à des fréquences différentes — par exemple, les définitions d'outils changent rarement, l'historique de conversation change à chaque tour. Chaque section peut avoir son propre point de rupture.
Règles d'invalidation du cache
Le cache est sensible à l'ordre. Tout changement apporté à un bloc mis en cache, ou à tout bloc qui le précède dans le prompt, invalide le cache à ce point de rupture et à tous ceux qui suivent.
Les changements apportés aux définitions d'outils invalident tous les caches. Les changements apportés au prompt système invalident les caches du système et des messages. Les changements en cours de conversation n'affectent que le cache des messages.
L'implication pratique : si vous injectez quoi que ce soit qui change à chaque requête, assurez-vous absolument que cela vit après le dernier point de rupture de cache, pas avant ni à l'intérieur.
Préchauffage et surveillance
Vous pouvez préchauffer le cache avant l'arrivée du trafic utilisateur en envoyant une requête avec max_tokens: 0 — cela écrit le cache sans générer de sortie. Utile pour les traitements par lots ou pour avancer le coût d'écriture pendant les heures creuses.
Le champ usage de la réponse de l'API vous indique combien de tokens ont été lus depuis le cache (cache_read_input_tokens), écrits dans le cache (cache_creation_input_tokens), et facturés comme entrée régulière. Surveillez-les pour vérifier que votre cache fonctionne réellement et pour mesurer les économies que vous réalisez.
Utilisez le Calculateur de coûts pour modéliser les économies attendues avant de vous engager dans une architecture de cache.
En résumé
Le cache de prompt n'est pas une micro-optimisation. Pour toute application qui envoie le même grand préfixe de façon répétée, c'est une décision économique structurelle. Le modèle pour y réfléchir est simple : le contenu stable d'abord, le contenu volatil en dernier, le point de rupture à la frontière.
Si vous construisez sur l'API et que vous n'avez pas encore regardé le cache, vérifiez vos prompts actuels à la recherche de grandes sections stables. Si elles existent, activer le cache demande généralement peu d'effort et les économies sont réelles.