Prompt caching Claude API : 90 % de coût en moins

Tu envoies le même system prompt à Claude 200 fois par jour. À chaque tour, le modèle relit tout. Et tu repaies tout. Le prompt caching d'Anthropic, c'est une seule clé à ajouter dans la requête, aucune réécriture du code, et le coût des tokens d'entrée s'effondre dès que tu réutilises un même bloc.

Pourquoi tu paies trop cher aujourd'hui

Tu utilises Claude pour un assistant qui répond à des questions sur ta documentation interne. Ton system prompt fait 4 000 tokens (instructions + extraits de doc). À chaque conversation, à chaque tour de cette conversation, l'API relit ces 4 000 tokens en input. Le tarif est facturé sur ces tokens même s'ils n'ont pas bougé.

Sur 200 requêtes par jour, sur un mois, sur plusieurs utilisateurs en parallèle, la facture monte vite. Le pire, c'est que ce contexte ne change pas. Tu paies l'inertie.

Activer le cache : une seule clé

Tu prends ta requête actuelle, tu rajoutes cache_control sur le bloc qui doit être caché. C'est tout.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {"role": "user", "content": "Question de l'utilisateur"}
    ],
)

Le bloc system (ici un long prompt + extraits de documentation) devient cachable. Au premier appel, Anthropic écrit le cache et te facture 1,25x ce tarif. Au deuxième appel sous 5 minutes avec le même bloc, c'est un hit : 0,10x.

Tu peux faire pareil sur les tools et sur des blocs user qui ne bougent pas.

Le gain réel sur les hits

Concrètement, si ton system prompt fait 4 000 tokens à 5 $/million sur Opus 4.7, sans cache c'est 0,02 $ par appel. Avec un hit caché, c'est 0,002 $. Sur 200 requêtes par jour, tu passes de 4 $/jour à 0,40 $/jour pour ce seul bloc. Et c'est avant de compter les hits sur les tools et le contexte conversationnel.

Le piège du premier hit

Le piège que la plupart des intégrations rate : l'écriture du cache est facturée 25 % plus cher que le tarif standard. Donc le premier appel coûte 1,25x au lieu de 1,00x. C'est seulement à partir du deuxième hit dans les 5 minutes que tu commences à être rentable.

Quand c'est rentable, quand c'est perdant

Mesurer le hit ratio en production

L'API renvoie dans la réponse les compteurs cache_creation_input_tokens et cache_read_input_tokens. Tu peux logger les deux et calculer ton hit ratio en continu.

usage = response.usage
hits = usage.cache_read_input_tokens
writes = usage.cache_creation_input_tokens
total_in = usage.input_tokens + hits + writes

hit_ratio = hits / total_in if total_in else 0
print(f"Hit ratio: {hit_ratio:.0%}")

Au-dessus de 30-40 % de hits, tu es nettement gagnant. En dessous, tu approches le break-even, et c'est un signal pour reconsidérer ton pattern de trafic ou désactiver le cache sur certains blocs.

Un hit ratio inférieur à 10 % en production veut dire que le cache te coûte plus cher qu'il ne te rapporte. Désactive sur les blocs concernés.

Les pièges côté code

Questions fréquentes

Pour aller plus loin

Active le cache sur ton bloc le plus volumineux, mesure le hit ratio sur 48 heures, et tu auras une vue chiffrée de ce que ça change vraiment chez toi. Si tu veux une revue de stack IA en agence, on en parle.