Analyse
Prompt caching Claude API : combien ça économise vraiment en 2026
La doc Anthropic explique le comment. Elle n’explique pas pourquoi votre chatbot coûte autant malgré le cache activé.
La réponse est dans trois angles morts que la documentation mentionne sans les quantifier : le TTL de 5 minutes, l’ordre des blocs qui détermine quels tokens sont réellement mis en cache, et le coût d’écriture que presque toutes les simulations oublient.
Mécanique réelle du prompt caching
Le prompt caching fonctionne par préfixe exact. Anthropic maintient une copie KV des tokens déjà traités côté serveur, indexée par hash du contenu. Quand votre requête présente le même préfixe qu’un appel précédent, les tokens cachés ne sont pas re-inférés — ils sont relus depuis la mémoire accélérée.
Deux compteurs pilotent la facture :
- Cache write : premier appel avec
cache_control: {"type": "ephemeral"}. Coût = prix input × 1,25. Vous payez 25 % de surcoût pour stocker. - Cache read : appels suivants sur le même préfixe dans la fenêtre TTL. Coût = prix input × 0,10. Réduction de 90 %.
Le TTL est de 5 minutes. Pas paramétrable sur les plans standard. C’est la contrainte la plus ignorée.
Flow cache hit vs cache miss
flowchart TD
accTitle: Cache hit vs cache miss selon TTL et préfixe
accDescr: Décision de facturation selon que le préfixe est en cache ou que le TTL de 5 minutes a expiré
A([Requête API]) --> B{Préfixe en cache\ndepuis moins de 5 min ?}
B -- Non ou TTL expiré --> C["Cache WRITE\n× 1,25 du prix input\n+25 %"]
B -- Oui --> D["Cache READ\n× 0,10 du prix input\n−90 %"]
C --> E[TTL 5 min démarre]
E --> F([Réponse])
D --> FTarification Sonnet 4.6 : les vrais chiffres
| Mode | $/MTok | Vs tarif standard |
|---|---|---|
| Input standard | $3,00 | référence |
| Cache write | $3,75 | +25 % |
| Cache read | $0,30 | −90 % |
| Output | $15,00 | inchangé |
La règle de seuil : 1 cache write ($3,75/MTok) + 1 cache read ($0,30/MTok) = $4,05/MTok — déjà 32 % moins cher que 2 appels standard ($6,00). Le ROI du caching est positif dès le 2ème appel dans la fenêtre TTL.
Autre contrainte souvent ignorée : le minimum de tokens pour activer le cache est de 2 048 tokens pour Claude Sonnet 4.6 (4 096 pour Opus 4.7). Un system prompt court n’est tout simplement pas mis en cache.
Trois profils, trois calculs
Profil 1 — Assistant documentation (100 000 tokens de contexte fixe)
Usage : chatbot interne sur 400 pages de documentation technique. System prompt de 100 k tokens transmis à chaque appel. 500 appels/jour, fenêtre concentrée sur 2 h (TTL respecté).
| Scénario | Coût input / jour |
|---|---|
| Sans cache | 500 × 100k tokens × $3/MTok = $150,00 |
| Avec cache (1 write + 499 reads) | $0,375 + $14,97 = $15,35 |
| Économie | −90 % |
Sur un mois de 22 jours ouvrés : $3 300 → $338. Économie de $2 962/mois. Pour cet usage, le prompt caching est probablement l’optimisation avec le meilleur ratio effort/gain disponible sur l’API Claude.
Profil 2 — Agent multi-tour : le piège du TTL
Usage : agent de support, 100 appels, contexte fixe 30 k tokens (system + outils). Deux scénarios opposés sur la même charge de travail.
| Scénario | Coût input / 100 appels |
|---|---|
| Haute vélocité (20 min, 1 write + 99 reads) | $0,113 + $0,891 = $1,00 |
| Basse vélocité (10 h, TTL expiré à chaque appel) | 100 × 30k × $3,75/MTok = $11,25 |
| Sans cache (référence) | 100 × 30k × $3/MTok = $9,00 |
En basse vélocité, le caching coûte 25 % de plus que sans cache. Chaque appel déclenche un cache write sans jamais obtenir de cache read. Vous payez la prime de stockage sans récupérer la remise.
Profil 3 — RAG batch nuit (préfixe commun 5 k tokens, 200 documents)
Usage : pipeline de traitement nuit, 200 documents traités en rafale en moins de 5 minutes. Instructions + system prompt = 5 k tokens partagés.
| Poste | Calcul | Montant |
|---|---|---|
| 1 cache write | 5k × $3,75/MTok | $0,019 |
| 199 cache reads | 199 × 5k × $0,30/MTok | $0,299 |
| Total avec cache | $0,318 | |
| Sans cache | 200 × 5k × $3/MTok | $3,00 |
| Économie | −89 % |
Ce que la doc ne dit pas : l’ordre des blocs
Anthropic construit les préfixes de cache dans un ordre précis : tools d’abord, system ensuite, messages en dernier. Votre cache_control doit être placé en tenant compte de cet ordre de construction.
Pour maximiser les cache hits :
- Tools (définitions d’outils) : le bloc le plus stable, idéal pour le premier breakpoint — particulièrement utile si vous orchestrez des agents via MCP
- System prompt : stable si vous n’y injectez pas de variables dynamiques
- Blocs de contexte statique (documents, base de connaissances) : dans les messages, avant l’historique
- Historique de conversation : toujours en fin, jamais mis en cache si possible
Erreur fréquente : placer cache_control uniquement sur le system prompt en croyant que les outils sont automatiquement inclus. Ils le sont — mais uniquement si votre tool block précède effectivement le system prompt dans la requête.
Le préfixe doit être identique à l’octet près. Un timestamp injecté dans le system prompt, un user ID, ou une variable d’environnement invalide le cache à chaque appel.
Instrumentation : lire les métriques
L’API retourne dans usage les champs cache_creation_input_tokens et cache_read_input_tokens. Sans logging de ces deux champs, vous naviguez à l’aveugle.
response = client.messages.create(...)
usage = response.usage
total_cacheable = (
usage.cache_read_input_tokens + usage.cache_creation_input_tokens
)
hit_rate = usage.cache_read_input_tokens / (total_cacheable + 0.001)
print(f"Cache hit rate: {hit_rate:.1%}")Un hit rate inférieur à 60 % sur un assistant documentaire signale soit un TTL non respecté, soit un préfixe instable.
Quand ne pas activer le cache
Trois cas où le caching est contre-productif :
- Contexte court sous le seuil minimum (< 2 048 tokens sur Sonnet 4.6) : l’API ignore silencieusement le
cache_control. - Conversations à faible vélocité : moins d’un tour toutes les 5 minutes — le TTL expire systématiquement, vous payez +25 % sans jamais récupérer la remise.
- Préfixe dynamique : si votre system prompt intègre l’heure courante, un ID utilisateur ou des données temps-réel, le hash change à chaque appel.
Pour tout le reste — batch traitement, assistants documentaires, agents à haute cadence — activez le caching. L’économie est réelle, et les 25 % de surcoût en écriture sont amortis dès le deuxième appel dans la fenêtre TTL.
Questions fréquentes
Le prompt caching est-il activé automatiquement ?
Non. Il faut ajouter explicitement cache_control: {"type": "ephemeral"} sur le bloc à cacher. Sans ce champ, tous vos tokens sont facturés au tarif input standard.
Que se passe-t-il si mon contexte est sous les 2 048 tokens ?
L’API ignore silencieusement le cache_control. Aucune erreur n’est retournée — vous payez le tarif input standard sans surcoût, mais aussi sans bénéfice. Vérifiez cache_creation_input_tokens dans usage : si toujours 0, votre contexte est sous le seuil.
Comment mesurer le ROI du caching dans mes logs ?
Utilisez les champs cache_creation_input_tokens et cache_read_input_tokens dans l’objet usage de chaque réponse API. Un ratio cache_read / (cache_read + cache_creation) supérieur à 80 % indique un caching efficace sur votre workload.