Prompt caching — réduire le coût et la latence

En bref

Le prompt caching est un mécanisme de l’API Anthropic qui permet de stocker une représentation interne d’un segment de prompt et de le réutiliser dans les requêtes suivantes. Quand un cache hit se produit, les tokens concernés sont facturés à 10% du tarif normal — soit une réduction de 90% sur cette portion. La latence (time to first token) peut baisser de plus de 85% pour les prompts longs.

Le principe est simple : au lieu de retraiter un contexte identique à chaque appel, le modèle récupère son état intermédiaire depuis un stockage temporaire. Pour un system prompt de 4 000 tokens envoyé à dix agents successifs, cela signifie un seul traitement complet et neuf récupérations à coût réduit.

Le caching opère sur des préfixes : tout le contenu situé avant un breakpoint désigné peut être mis en cache, à condition que ce préfixe soit identique d’une requête à l’autre. Un seul caractère différent en début de prompt invalide le cache pour tout ce qui suit.

Prérequis

Modèles supportés : tous les modèles Claude actuels (Opus 4.6, Sonnet 4.6, Haiku 4.5 et variantes antérieures). La fonctionnalité est active par défaut — aucune activation spéciale n’est requise, seulement le placement de cache_control dans la requête.

Version API minimum : 2023-06-01. Les requêtes sans en-tête anthropic-version ou avec une version antérieure ignorent les marqueurs cache_control sans erreur.

Longueur minimale cacheable : le contenu mis en cache doit dépasser un seuil de tokens pour être éligible.

En dessous du seuil, les marqueurs cache_control sont ignorés silencieusement. La requête aboutit, mais aucun cache n’est créé.

Isolation : depuis le 5 février 2026, les caches sont isolés au niveau du workspace (et non plus de l’organisation). Compatible avec les engagements Zero Data Retention (ZDR). Le stockage conserve des représentations KV et des hashes, pas de texte brut.

Étapes

Placer les breakpoints

Deux modes coexistent :

Cache automatique — un seul cache_control au niveau racine de la requête. Le système déplace automatiquement le breakpoint vers le dernier bloc cacheable au fur et à mesure que la conversation progresse. Recommandé pour les conversations multi-tours.

Breakpoints explicites — cache_control placé directement sur des blocs de contenu individuels. Jusqu’à quatre breakpoints par requête. Utile quand différentes sections changent à des fréquences différentes (les outils changent rarement, le system prompt parfois, les messages souvent).

{
  "system": [{
    "type": "text",
    "text": "Votre long system prompt ici...",
    "cache_control": {"type": "ephemeral"}
  }]
}

Conditions d’un cache hit

Le préfixe doit être 100% identique depuis le début jusqu’au breakpoint. Le système vérifie jusqu’à 20 blocs en arrière depuis chaque breakpoint explicite. Si aucune correspondance n’est trouvée dans ces 20 blocs, aucun hit n’est produit.

Un bloc mis en cache reste éligible aux hits même s’il n’est pas re-marqué dans les requêtes suivantes — tant qu’il est dans sa fenêtre TTL.

TTL et coûts d’écriture

Le TTL par défaut est de 5 minutes ({"type": "ephemeral"}). Le TTL étendu à une heure s’active avec {"type": "ephemeral", "ttl": "1h"}. Les refreshes dans la fenêtre TTL sont gratuits — relire un contenu en cache le renouvelle sans coût supplémentaire.

Le cache 1 heure vaut l’investissement quand le contenu est réutilisé moins d’une fois toutes les 5 minutes mais plus d’une fois par heure — typiquement : workflows agents de longue durée, conversations avec pauses utilisateur, ou prompts partagés entre sessions espacées.

Stratégies d’optimisation

Placer le contenu le plus stable en premier (définitions d’outils, instructions système), puis le contenu variable (messages, contexte de tâche). La hiérarchie de cascade est : Tools → System → Messages — un changement dans les outils invalide le cache de tout ce qui suit.

Pour suivre les performances, la réponse API inclut trois champs dans usage :

• cache_read_input_tokens : tokens récupérés depuis le cache (facturés à 0,1×)
• cache_creation_input_tokens : nouveaux tokens écrits en cache (facturés à 1,25×)
• input_tokens : tokens après le dernier breakpoint, non cachés (facturés à 1×)

Pièges courants

Invalidation silencieuse

Plusieurs paramètres invalident le cache sans erreur explicite. Le tableau suivant liste les modifications qui cassent le cache selon leur portée :

Un changement de configuration anodin en apparence — passer tool_choice de auto à any — peut vider le cache des messages. Surveiller cache_creation_input_tokens dans les réponses : un pic inattendu signale une invalidation.

Parallélisme et cache

Point critique pour l’orchestration multi-agents : le cache n’est disponible qu’après le début de la première réponse. Des agents lancés strictement en simultané ne garantissent pas de bénéficier du cache créé par le premier agent. D’après nos observations, la stratégie “cache warmer” — lancer un premier agent pour établir le cache, attendre son démarrage, puis lancer les agents parallèles — est une approche viable, mais son efficacité réelle dépend du timing réseau et n’a pas encore été mesurée empiriquement.

En revanche, nos tests montrent que les cache hits ne comptent pas dans les rate limits ITPM (Input Tokens Per Minute). Pour du parallélisme massif, cela libère du budget rate limit pour la partie variable des prompts.

Coût du write : rentabilité à calculer

Un cache write 5 min coûte 1,25× le tarif standard — 25% plus cher que sans caching. La rentabilité apparaît dès le deuxième hit : 1 write (1,25×) + 1 hit (0,1×) = 1,35× pour deux requêtes, contre 2× sans cache. À partir de trois requêtes, le gain est net.

Pour le cache 1 heure (2× à l’écriture), il faut au moins trois hits pour amortir le surcoût d’écriture.

Minimum tokens : attention aux petits prompts

Un system prompt de 1 500 tokens envoyé à Claude Sonnet 4.6 (seuil : 2 048) ne sera jamais mis en cache. Le marqueur cache_control est ignoré sans avertissement. Vérifier que le contenu à cacher dépasse effectivement le seuil du modèle cible avant de compter sur le caching dans les calculs de coût.

Nos tests sur des workflows multi-agents montrent que le system prompt combiné (instructions globales + instructions projet) atteint généralement 2 000 à 4 000 tokens — juste au-dessus du seuil Sonnet, mais parfois en dessous du seuil Opus et Haiku 4.5. Ajuster le contenu ou le modèle en conséquence.

Ce qu’il faut retenir

• Le prompt caching réduit jusqu’à 90% le coût des tokens en cache et jusqu’à 85% la latence — mais seulement si le préfixe est strictement identique d’un appel à l’autre.
• Le seuil minimum de tokens varie selon le modèle (1 024 à 4 096) : en dessous, le marqueur cache_control est ignoré silencieusement.
• Le cache write coûte 1,25× (5 min) ou 2× (1 heure) le tarif standard — la rentabilité commence dès le deuxième hit pour le TTL court, le troisième pour le TTL long.
• En orchestration multi-agents, les cache hits n’affectent pas les rate limits ITPM — avantage concret pour le parallélisme massif.
• Placer le contenu stable en premier (outils, instructions système) : un changement en tête de prompt invalide tout le cache en cascade.

Sources

• Prompt caching — Anthropic Docs, consulté le 2026-03-19
• Pricing — Claude API Docs, consulté le 2026-03-19
• Rate limits — Claude API Docs, consulté le 2026-03-19