Mise en cache des prompts chez Anthropic : le réglage qui divise la facture d'entrée

Un assistant interne qui s'appuie sur un long règlement, un agent qui embarque trente définitions d'outils : à chaque appel, le même texte repart vers le modèle et se paie plein tarif. La mise en cache des prompts (« prompt caching ») sert à éviter cela. Le début de la requête est mémorisé côté Anthropic et relu à prix réduit lors des appels suivants.

L'activer en une ligne

La méthode la plus simple est la mise en cache automatique : un champ cache_control placé à la racine de la requête.

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "Vos instructions longues…",
  "messages": [{"role": "user", "content": "Votre question"}]
}

Le système place lui-même le point de cache sur le dernier bloc qui peut l'être, et le déplace à mesure que la conversation s'allonge.

Pour un contrôle plus fin, le même champ se pose sur un bloc précis, par exemple le texte du prompt système. La documentation autorise quatre points de cache explicites par requête ; le mode automatique en consomme un.

Durée de vie : cinq minutes ou une heure

• Par défaut, l'entrée vit 5 minutes. Chaque relecture la prolonge sans frais.
• Avec {"type": "ephemeral", "ttl": "1h"}, elle vit une heure.

Si les deux durées cohabitent dans une requête, les blocs à une heure doivent précéder ceux à cinq minutes.

Ce que cela coûte

Les tarifs sont exprimés en multiples du prix d'entrée normal :

• écriture dans le cache pour 5 minutes : 1,25 fois le prix ;
• écriture pour 1 heure : 2 fois le prix ;
• relecture : 0,1 fois le prix, et moins encore sur les modèles récents (0,05 fois pour Opus 5.5 et Sonnet 5.5, 0,025 fois pour Fable 5.1 et 5.2).

Exemple tiré de la grille publiée : sur Claude Sonnet 5.5, le million de jetons d'entrée coûte 2 dollars, son écriture en cache 2,50 dollars et sa relecture 0,10 dollar. Le premier appel coûte donc un peu plus cher, tous les suivants beaucoup moins.

Vérifier que le cache fonctionne

La réponse contient, dans l'objet usage, deux compteurs à surveiller :

• cache_creation_input_tokens : jetons écrits dans le cache ;
• cache_read_input_tokens : jetons relus depuis le cache.

Si les deux restent à zéro, rien n'a été mis en cache. La cause la plus fréquente est un prompt trop court : le seuil minimal est de 512 jetons sur les modèles les plus récents, et monte à 1 024, 2 048 ou 4 096 jetons sur des modèles plus anciens (4 096 pour Haiku 4.5, par exemple). En dessous, l'API ne renvoie aucune erreur, elle traite simplement la requête sans cache.

Les pièges

• L'ordre compte. Le cache suit la hiérarchie outils, puis système, puis messages. Modifier une définition d'outil invalide tout ; modifier le prompt système invalide aussi les messages.
• Identique au caractère près. Une date ou un identifiant glissé au début du prompt suffit à empêcher toute relecture. Placez le contenu stable en premier, le contenu variable à la fin.
• Requêtes simultanées. Une entrée n'est disponible qu'une fois que la première réponse a commencé. Lancer dix appels en parallèle sur un cache vide revient à payer dix écritures.

Pour ce dernier cas, la documentation décrit un préchauffage : une requête avec max_tokens: 0 écrit le cache sans générer de texte. Elle est refusée en mode streaming et dans les traitements par lots.

Notre lecture

Pour une petite équipe, c'est souvent l'optimisation la plus rentable par ligne de code. Elle ne vaut toutefois que si le trafic est assez régulier : avec un appel toutes les vingt minutes, le cache de cinq minutes expire à chaque fois et l'on paie le surcoût d'écriture sans jamais relire. Dans ce cas, comparez avec la durée d'une heure, plus chère à l'écriture. Mesurez sur une semaine, compteurs usage à l'appui, avant de conclure. Les prix cités, en dollars, sont ceux de la documentation à la date de notre lecture.