Prompt Caching

Mettre en cache les parties stables de votre prompt pour diviser coûts et latence sur les appels répétés.

Le prompt caching permet à Claude de réutiliser le travail de traitement d'une partie de prompt entre plusieurs appels. Résultat : les tokens en cache coûtent ~10× moins cher et sont traités beaucoup plus vite.

Quand l'utiliser ?

Dès qu'une partie de votre prompt est stable et réutilisée :

• Un long system prompt avec instructions détaillées
• Un contexte documentaire (RAG, connaissances persistantes)
• Des exemples few-shot longs
• L'historique d'une conversation qui s'allonge

Comment activer le cache

Ajoutez cache_control sur les blocs que vous voulez mettre en cache :

const message = await client.messages.create({
  model: 'claude-opus-4-7',
  max_tokens: 1024,
  system: [
    {
      type: 'text',
      text: 'Tu es un assistant juridique spécialisé en droit français...',
      cache_control: { type: 'ephemeral' }
    }
  ],
  messages: [
    { role: 'user', content: 'Résume l\'article 1240 du Code civil.' }
  ]
});

Règles importantes

Coût d'écriture du cache

Écrire dans le cache coûte plus cher qu'un token input standard — c'est le prix à amortir sur les lectures :

• Cache write TTL 5 min : 1.25× le prix input
• Cache write TTL 1 h : 2× le prix input
• Cache read (hit) : 0.1× le prix input

Seuil de rentabilité (en comptant la 1re requête qui écrit le cache) :

• TTL 5 min : rentable dès la 2e utilisation du bloc (1 write à 1.25× + 1 read à 0.1× = 1.35× contre 2× sans cache).
• TTL 1 h : rentable dès la 3e utilisation (le surcoût d'écriture de +1× met une relecture de plus à être absorbé).

Chaque relecture supplémentaire économise 0.9× le prix input.

Mesurer l'impact

L'objet de réponse contient les compteurs de cache :

{
  "usage": {
    "cache_creation_input_tokens": 2048,
    "cache_read_input_tokens": 0,
    "input_tokens": 120,
    "output_tokens": 340
  }
}

Un bon indicateur de santé : le ratio cache_read / (cache_read + cache_creation). En production, visez > 80 %.