La nouvelle API de prompt-caching de Claude Opus 5 réduit considérablement la facture de tokens pour les applications de type chat en permettant au modèle de ne pas relire le texte inchangé. La première requête entraîne un léger surcoût ; chaque appel suivant coûte environ un dixième du tarif de base, transformant une dépense récurrente en un coût unique.

Pourquoi les développeurs paient deux fois pour les mêmes mots

La plupart des interfaces conversationnelles reconstruisent l'intégralité du prompt à chaque tour : un prompt système de 8 000 tokens, des PDF joints et l'historique complet du dialogue sont envoyés ensemble au modèle chaque fois qu'un utilisateur pose une question de suivi. Le modèle traite à nouveau chaque token, même si la majeure partie de ce texte ne change jamais. Avec les tarifs actuels, cette redondance peut représenter la majeure partie du coût d'un bot très sollicité.

Comment le cache modifie le calcul

L'API crée une entrée de cache pour chaque « bloc » de tokens jusqu'à un point de rupture défini. Lorsque la requête suivante contient le même bloc au début, le service le lit depuis le cache au lieu de le tokenizer à nouveau. La répartition des prix reflète le travail économisé :

  • Écriture en cache – TTL de 5 minutes : 1,25 × prix de base
  • Écriture en cache – TTL de 1 heure : 2 × prix de base
  • Lecture en cache (hit) : 0,1 × prix de base

En pratique, le premier appel à un nouveau bloc coûte un peu plus cher qu'une requête normale. Chaque appel ultérieur qui sollicite le cache est 90 % moins cher, de sorte que la dépense nette chute radicalement à mesure que la conversation progresse.

La « règle d'or » pour structurer les prompts

L'efficacité du cache dépend de l'endroit où vous placez le contenu statique par rapport au contenu dynamique. Placez tout ce qui reste identique au début, et repoussez les éléments changeants à la fin. Un ordre fiable ressemble à ceci :

  1. Outils (Tools) – définitions de toutes les fonctions externes que le modèle peut appeler.
  2. Instructions système (System instructions) – le comportement de haut niveau que vous souhaitez que le modèle suive.
  3. Documents – contexte long tel que des PDF, des bases de connaissances ou des extraits de politiques.
  4. Questions de l'utilisateur (User questions) – la requête en direct qui varie à chaque tour.

Si vous modifiez un seul token avant un point de rupture, l'entrée de cache est invalidée et le modèle doit retraiter tout ce qui suit.

Limites cachées à respecter

  • Taille minimale du bloc – Opus 5 ne met en cache que les blocs contenant au moins 512 tokens. Tout ce qui est plus petit échappe entièrement au cache.
  • Bug de l'horodatage (timestamp) – l'insertion d'un horodatage changeant à l'intérieur d'un bloc mis en cache garantit un échec (miss), car le texte du bloc ne correspondra jamais exactement.
  • Fenêtre de recherche de 20 blocs – le service ne scanne que les 20 derniers blocs pour trouver une correspondance. Les sessions de longue durée qui progressent rapidement peuvent dépasser la fenêtre du cache.
  • Requêtes parallèles – l'envoi de plusieurs requêtes identiques au même instant entraînera des échecs pour toutes, car le cache n'est alimenté qu'une fois la première requête terminée. Chauffez le cache avec un seul appel, puis lancez le reste.

Visualiser les économies dans votre réponse API

Chaque réponse indique trois compteurs de tokens :

  • cache_read_input_tokens – tokens provenant d'un succès de cache (hit).
  • cache_creation_input_tokens – tokens écrits dans le cache lors de cette requête.
  • input_tokens – les nouveaux tokens qui n'étaient pas en cache.

Additionnez ces trois nombres pour obtenir le nombre total de tokens pris en compte par le modèle pour ce tour. Si les deux champs de cache sont à zéro, la requête a manqué le cache ; vérifiez la taille de vos blocs et le placement de vos points de rupture.

À retenir : En plaçant le contexte immuable en tête de requête et en laissant l'API de prompt-caching de Claude Opus 5 faire le gros du travail, vous transformez une dépense de tokens récurrente en un coût unique. Le résultat est une réduction spectaculaire des coûts pour tout chatbot qui fait référence de manière répétée au même prompt système ou au même ensemble de documents — à condition de respecter le seuil minimal de tokens, d'éviter les marqueurs variables à l'intérieur des blocs mis en cache et de maintenir votre contenu éligible au cache dans l'horizon des 20 blocs.