Avancé

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

What you'll learn

Pourquoi l'appel API naïf paie trop : le même préfixe stable traité depuis zéro, à chaque fois
Le modèle mental — préfixe stable, suffixe volatil — et la seule règle d'ordre qui rend le cache possible
Le split tarifaire à trois voies pour l'entrée (écriture cache, lecture cache, entrée normale) et quand le point de croisement rentabilise
Quand le cache gagne sa place, et les quatre scénarios où il ne le fait pas silencieusement
Les cinq règles d'invalidation du cache qui décident si votre taux de succès est de 90 % ou de 0 %
Comment préchauffer le cache et lire les champs d'usage pour prouver que vos économies sont réelles

À chaque appel à l'API 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 faites de nombreux appels avec le même grand préfixe, vous payez pour traiter ce préfixe depuis zéro à chaque fois.

Le cache de prompt change ça. Vous marquez une portion stable de votre prompt comme cacheable. Le premier appel la traite et la stocke. Les appels suivants qui touchent 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 à livrer » à « quasi gratuit à faire tourner ».

Le modèle mental : préfixe stable, suffixe volatil

Pensez à chaque appel API comme à deux parties :

Le préfixe stable — 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 — contenu qui change par appel. C'est là que le cache ne s'applique pas. Exemples :

Le message utilisateur actuel
Données en temps réel injectées par requête
L'historique de conversation qui grandit à chaque tour

La règle est simple : structurez vos prompts pour que le contenu stable vienne en premier et que le contenu changeant vienne en dernier. Les points de rupture du cache sont positionnels — tout ce qui est avant le point marqué est éligible au cache ; tout ce qui est après ne l'est pas.

Si vous mettez du contenu dynamique avant du contenu statique, vous cassez le cache, parce que le préfixe change à chaque requête.

Comment fonctionne le modèle de coût

Le cache de prompt introduit un split à trois voies dans la tarification des tokens d'entrée :

Type de token	Quand ça arrive	Coût relatif à l'entrée normale
Écriture cache	Premier appel, ou après expiration du cache	Plus élevé que l'entrée normale
Lecture cache	Appels suivants qui touchent le cache	Beaucoup plus bas que l'entrée normale
Entrée normale	Tokens après le dernier point de rupture cache	Tarif normal

Les multiplicateurs exacts sont sur la page tarifaire officielle et fluctuent — vérifiez-les directement. Ce qui ne change pas est la structure : les écritures coûtent plus que la normale, les lectures coûtent beaucoup moins. Le point de croisement — quand vous avez fait assez d'appels en cache pour récupérer le surcoût d'écriture — arrive rapidement sur tout prompt avec un contenu stable substantiel.

La latence suit le même schéma. Les lectures cache sautent le traitement complet de la portion 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 vraies simultanément :

Vous avez un préfixe stable substantiel (il existe un seuil minimum de tokens en dessous duquel le cache n'est pas disponible — vérifiez les docs actuelles pour le nombre exact par modèle).
Vous faites en sorte que ce préfixe soit réutilisé assez fréquemment pour toucher le cache plus qu'occasionnellement.

Scénarios où le cache est un ajustement naturel :

Q&R sur documents — le même grand document est injecté pour de nombreuses questions utilisateur.
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 workflow multi-étapes.
Agents conversationnels avec de longues instructions — une personnalité détaillée, un ensemble 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 template.

Quand le cache de prompt n'aide pas

Le cache n'est pas utile quand :

Vos prompts sont courts (en dessous du seuil minimum de tokens cacheables).
Votre préfixe change à chaque appel — injecter un timestamp, un contexte spécifique à l'utilisateur ou toute personnalisation dans la partie « stable » invalide le cache.
Vous faites des appels peu fréquents avec de longs écarts entre eux. Le contenu en cache expire après un TTL (une durée que vous pouvez configurer, dans les limites que l'API supporte). Si votre trafic est clairsemé, vous paierez majoritairement des coûts d'écriture avec peu de lectures.
Votre préfixe est petit par rapport au contenu dynamique par appel. Les économies évoluent avec la taille de ce qui est mis en cache.

Structurer les prompts pour être cache-friendly

La seule exigence structurelle est l'ordre : le contenu stable doit venir avant le contenu volatil.

Guided walkthrough1 of 5

Instructions, personnalité, règles — les parties qui ne changent jamais par requête utilisateur.

Forme de prompt cache-friendly

[System prompt — instructions, persona, rules]
[Tool definitions — if static]
[Large injected documents or context — same across calls]
--------- cache breakpoint here ---------
[Dynamic per-call content — user message, retrieved chunks]

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 est avant ce marqueur est éligible au cache ; tout ce qui est après est de l'entrée normale.

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 à un bloc en cache, ou à tout bloc qui vient avant lui dans le prompt, invalide le cache à ce point de rupture et à tous les suivants.

Watch out

Les changements dans les définitions d'outils invalident TOUS les caches — traitez la liste d'outils comme maximalement stable.
Les changements dans le prompt système invalident les caches système et messages.
Les changements en cours de conversation n'affectent que le cache des messages.
Injecter un timestamp, un ID utilisateur ou une personnalisation par requête dans une section « stable » tue silencieusement votre taux de succès — ce contenu appartient APRÈS le dernier point de rupture.
Espaces, ponctuation et ordre comptent à l'octet près — les « petites » modifications invalident quand même.

L'implication pratique : si vous injectez quoi que ce soit qui change par requête, assurez-vous absolument que ça vit après le dernier point de rupture cache, pas avant ni dedans.

Préchauffage et monitoring

Vous pouvez préchauffer le cache avant l'arrivée du trafic utilisateur en envoyant une requête avec max_tokens: 0 — cela écrit dans le cache sans générer de sortie. Utile pour les jobs par lots ou pour anticiper le coût d'écriture pendant les heures creuses.

Le champ usage de la réponse API vous dit 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 normale. Monitorez ces valeurs pour vérifier que votre cache touche vraiment et pour mesurer les économies que vous réalisez.

Lisez le champ usage pour prouver que le cache marche

# From any Claude API response, inspect response.usage:
{
"usage": {
  "input_tokens": 42,                    # billed at normal rate
  "cache_creation_input_tokens": 0,      # tokens written on this call
  "cache_read_input_tokens": 8912,       # tokens served from cache (cheap)
  "output_tokens": 384
}
}
# Healthy state after warm-up: cache_read >> cache_creation, run over run.
# If cache_creation stays high, something upstream of your breakpoint is changing.

Utilisez le Calculateur de coûts pour modéliser les économies attendues avant de vous engager sur une architecture de cache.

Le bilan

Le cache de prompt n'est pas une micro-optimisation. Pour toute application qui envoie le même grand préfixe de manière répétée, c'est une décision économique structurelle. Le modèle pour y penser est direct : le contenu stable vient en premier, le contenu volatil en dernier, mettez le point de rupture à la frontière.

Si vous construisez contre l'API et n'avez pas encore regardé le cache, vérifiez vos prompts actuels pour de grandes sections stables. Si elles existent, activer le cache est généralement peu coûteux en effort et les économies sont réelles.

Vérifiez-vous

0/5

Où dans une requête le point de rupture cache doit-il se situer pour que le cache fonctionne ?
Quel coût est PLUS élevé qu'un token d'entrée normal ?
Vous injectez le timestamp actuel en haut de chaque requête « pour que le modèle connaisse l'heure ». Qu'arrive-t-il au cache ?
Comment prouver que le cache vous fait réellement économiser de l'argent en production ?
Vous changez un seul mot dans vos définitions d'outils. Qu'est-ce qui est invalidé ?

Key takeaways

Le cache divise la tarification d'entrée en trois : écriture cache (prime), lecture cache (bon marché), entrée normale (normal) — le gain évolue avec la taille du préfixe × la fréquence de réutilisation.
Une règle façonne les prompts cache-friendly : contenu stable AVANT le point de rupture, contenu volatil APRÈS — inversez ça et le cache meurt à chaque requête.
Vous pouvez placer jusqu'à quatre points de rupture pour que outils, prompt système, docs et historique cachent chacun à leur propre fréquence.
Tout changement à un bloc en cache — ou à tout bloc plus tôt dans le prompt — invalide ce point de rupture et tous les suivants.
Prouvez les économies avec cache_read_input_tokens vs cache_creation_input_tokens dans le champ usage, et préchauffez avec max_tokens: 0 pour les jobs par lots.
Sautez le cache quand les préfixes sont courts, le trafic clairsemé (le contenu en cache expire), ou le préfixe petit par rapport au contenu dynamique par appel.

Le modèle mental : préfixe stable, suffixe volatil​

Comment fonctionne le modèle de coût​

Quand le cache de prompt aide​

Quand le cache de prompt n'aide pas​

Structurer les prompts pour être cache-friendly​

Forme de prompt cache-friendly

Règles d'invalidation du cache​

Préchauffage et monitoring​