Mise en cache des prompts

Le « prompt caching » (mise en cache des prompts) optimise votre utilisation de l'API en permettant de reprendre à partir de préfixes spécifiques dans vos prompts. Cela réduit considérablement le temps de traitement et les coûts pour les tâches répétitives ou les prompts comportant des éléments constants.

Il existe deux façons d'activer la mise en cache des prompts :

• Mise en cache automatique : ajoutez un seul champ cache_control au niveau supérieur de votre requête. Le système applique automatiquement le « cache breakpoint » (point d'arrêt de cache) au dernier bloc pouvant être mis en cache et le fait avancer à mesure que les conversations s'allongent. Cette méthode est idéale pour les conversations multi-tours où l'historique croissant des messages doit être mis en cache automatiquement.
• Points d'arrêt de cache explicites : placez cache_control directement sur des blocs de contenu individuels pour contrôler précisément ce qui est mis en cache.

La façon la plus simple de commencer est d'utiliser la mise en cache automatique :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

Avec la mise en cache automatique, le système met en cache tout le contenu jusqu'au dernier bloc pouvant être mis en cache inclus. Lors des requêtes suivantes ayant le même préfixe, le contenu mis en cache est réutilisé automatiquement.

Fonctionnement de la mise en cache des prompts

Lorsque vous envoyez une requête avec la mise en cache des prompts activée :

1. Le système vérifie si un préfixe de prompt, jusqu'à un point d'arrêt de cache spécifié, est déjà en cache à la suite d'une requête récente.
2. S'il est trouvé, il utilise la version en cache, ce qui réduit le temps de traitement et les coûts.
3. Sinon, il traite le prompt complet et met le préfixe en cache dès que la réponse commence.

Ceci est particulièrement utile pour :

• Les prompts comportant de nombreux exemples
• De grandes quantités de contexte ou d'informations de référence
• Les tâches répétitives avec des instructions constantes
• Les longues conversations à plusieurs tours

Par défaut, le cache a une durée de vie de 5 minutes. Le cache est actualisé sans coût supplémentaire chaque fois que le contenu mis en cache est utilisé.

La durée de vie est mesurée à partir du début de la requête qui écrit ou lit l'entrée de cache, et non à partir de la fin de sa réponse. Le temps passé à générer une réponse est décompté de la durée de vie : si une réponse met 4 minutes à être transmise en streaming, une requête de suivi qui réutilise le même préfixe en cache doit commencer dans un délai d'environ 1 minute après la fin de cette réponse.

Tarification

La mise en cache des prompts introduit une nouvelle structure tarifaire. Le tableau suivant indique le prix par million de tokens pour chaque modèle pris en charge :

Model	Base tokens		Prompt caching
Name	Input	Output	5m writes	1h writes	Hits and refreshes
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work	$4 / MTok	$20 / MTok	$5 / MTok	$8 / MTok	$0.20 / MTok2
Claude Sonnet 5The best combination of speed and intelligence	$2 / MTok	$10 / MTok	$2.50 / MTok	$4 / MTok	$0.20 / MTok
Claude Haiku 4.5The fastest model with near-frontier intelligence	$1 / MTok	$5 / MTok	$1.25 / MTok	$2 / MTok	$0.10 / MTok
Additional models
Claude Mythos 5.1	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$0.25 / MTok1
Claude Fable 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Mythos 5	$10 / MTok	$50 / MTok	$12.50 / MTok	$20 / MTok	$1 / MTok
Claude Opus 5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.8	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.7	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.6	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.5	$5 / MTok	$25 / MTok	$6.25 / MTok	$10 / MTok	$0.50 / MTok
Claude Opus 4.1	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Opus 4	$15 / MTok	$75 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok
Claude Sonnet 4.6	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4.5	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Sonnet 4	$3 / MTok	$15 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok
Claude Haiku 3.5	$0.80 / MTok	$4 / MTok	$1 / MTok	$1.60 / MTok	$0.08 / MTok

^{1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price.}

^{2 Cache hits and refreshes on Claude Opus 5.5 are priced at 0.05x the base input price.}

^{All other models use the standard 0.1x multiplier.}

Modèles pris en charge

La mise en cache des prompts (automatique et explicite) est prise en charge sur tous les modèles Claude actifs.

Mise en cache automatique

La mise en cache automatique est la façon la plus simple d'activer la mise en cache des prompts. Au lieu de placer cache_control sur des blocs de contenu individuels, ajoutez un seul champ cache_control au niveau supérieur du corps de votre requête. Le système applique automatiquement le point d'arrêt de cache au dernier bloc pouvant être mis en cache.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a helpful assistant that remembers our conversation.",
    messages=[
        {"role": "user", "content": "My name is Alex. I work on machine learning."},
        {
            "role": "assistant",
            "content": "Nice to meet you, Alex! How can I help with your ML work today?",
        },
        {"role": "user", "content": "What did I say I work on?"},
    ],
)
print(response.usage.model_dump_json())

Fonctionnement de la mise en cache automatique dans les conversations multi-tours

Avec la mise en cache automatique, le point de cache avance automatiquement à mesure que les conversations s'allongent. Chaque nouvelle requête met en cache tout le contenu jusqu'au dernier bloc pouvant être mis en cache, et le contenu précédent est lu depuis le cache.

Le point d'arrêt de cache se déplace automatiquement vers le dernier bloc pouvant être mis en cache dans chaque requête, vous n'avez donc pas besoin de mettre à jour les marqueurs cache_control à mesure que la conversation s'allonge.

Prise en charge du TTL

Par défaut, la mise en cache automatique utilise un « time to live » (durée de vie), ou TTL, de 5 minutes. Vous pouvez spécifier un TTL d'une heure pour 2 fois le prix de base des tokens d'entrée :

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

Combinaison avec la mise en cache au niveau des blocs

La mise en cache automatique est compatible avec les points d'arrêt de cache explicites. Lorsqu'ils sont utilisés ensemble, le point d'arrêt de cache automatique occupe l'un des 4 emplacements de point d'arrêt disponibles.

Cela vous permet de combiner les deux approches. Par exemple, utilisez un point d'arrêt explicite pour mettre en cache votre « system prompt » (invite système), tandis que la mise en cache automatique gère la conversation :

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

Ce qui reste identique

La mise en cache automatique utilise la même infrastructure de mise en cache sous-jacente. La tarification, les seuils minimaux de tokens, les exigences d'ordre du contexte et la « lookback window » (fenêtre de rétrospection) de 20 blocs s'appliquent tous de la même manière qu'avec les points d'arrêt explicites.

Cas particuliers

• Si le dernier bloc possède déjà un cache_control explicite avec le même TTL, la mise en cache automatique n'a aucun effet.
• Si le dernier bloc possède un cache_control explicite avec un TTL différent, l'API renvoie une erreur 400.
• Si 4 points d'arrêt explicites au niveau des blocs existent déjà, l'API renvoie une erreur 400 (aucun emplacement restant pour la mise en cache automatique).
• Si le dernier bloc n'est pas éligible comme cible de point d'arrêt de cache automatique, le système remonte silencieusement pour trouver le bloc éligible le plus proche. Si aucun n'est trouvé, la mise en cache est ignorée.

Points d'arrêt de cache explicites

Pour un meilleur contrôle de la mise en cache, vous pouvez placer cache_control directement sur des blocs de contenu individuels. Ceci est utile lorsque vous devez mettre en cache différentes sections qui changent à des fréquences différentes, ou lorsque vous avez besoin d'un contrôle précis de ce qui est mis en cache.

Structurer votre prompt

Placez le contenu statique (définitions d'outils, instructions système, contexte, exemples) au début de votre prompt. Marquez la fin du contenu réutilisable à mettre en cache à l'aide du paramètre cache_control.

Les préfixes de cache sont créés dans l'ordre suivant : tools, system, puis messages. Cet ordre forme une hiérarchie dans laquelle chaque niveau s'appuie sur les précédents.

Fonctionnement de la vérification automatique des préfixes

Vous pouvez utiliser un seul point d'arrêt de cache à la fin de votre contenu statique, et le système trouvera automatiquement le préfixe le plus long qu'une requête antérieure a déjà écrit dans le cache. Comprendre ce fonctionnement vous aide à optimiser votre stratégie de mise en cache.

Trois principes fondamentaux :

1. Les écritures en cache ont lieu uniquement à votre point d'arrêt. Marquer un bloc avec cache_control écrit exactement une entrée de cache : un hachage du préfixe se terminant à ce bloc. Le système n'écrit aucune entrée pour une position antérieure. Comme le hachage est cumulatif et couvre tout le contenu jusqu'au point d'arrêt inclus, la modification de n'importe quel bloc situé au niveau du point d'arrêt ou avant celui-ci produit un hachage différent lors de la requête suivante.

2. Les lectures du cache remontent en arrière à la recherche d'entrées écrites par des requêtes antérieures. À chaque requête, le système calcule le hachage du préfixe à votre point d'arrêt et recherche une entrée de cache correspondante. S'il n'en existe aucune, il remonte un bloc à la fois, en vérifiant si le hachage du préfixe à chaque position antérieure correspond à quelque chose déjà présent dans le cache. Il recherche des écritures antérieures, et non du contenu stable.

3. La fenêtre de rétrospection est de 20 blocs. Le système vérifie au maximum 20 positions par point d'arrêt, en comptant le point d'arrêt lui-même comme la première. Si le système ne trouve aucune entrée correspondante dans cette fenêtre, la vérification s'arrête (ou reprend à partir du point d'arrêt explicite suivant, s'il y en a un). Sur l'API Claude, une suite de blocs tool_use consécutifs compte comme une seule position, de même qu'une suite de blocs tool_result consécutifs ; ainsi, un tour comportant de nombreux appels d'outils parallèles ne repousse pas à lui seul l'entrée de la requête précédente hors de la fenêtre.

Exemple : rétrospection dans une conversation qui s'allonge

Vous ajoutez de nouveaux blocs à chaque tour et définissez cache_control sur le dernier bloc de chaque requête :

• Tour 1 : 10 blocs, point d'arrêt sur le bloc 10. Aucune entrée de cache antérieure n'existe. Le système écrit une entrée au bloc 10.
• Tour 2 : 15 blocs, point d'arrêt sur le bloc 15. Le bloc 15 n'a pas d'entrée, le système remonte donc jusqu'au bloc 10 et trouve l'entrée du tour 1. « Cache hit » (succès de cache) au bloc 10 ; le système ne traite à nouveau que les blocs 11 à 15 et écrit une nouvelle entrée au bloc 15.
• Tour 3 : 35 blocs, point d'arrêt sur le bloc 35. Le système vérifie 20 positions (blocs 35 à 16) et ne trouve rien. L'entrée du tour 2 au bloc 15 se trouve une position en dehors de la fenêtre, il n'y a donc pas de succès de cache. L'ajout d'un second point d'arrêt au bloc 15 démarre une seconde fenêtre de rétrospection à cet endroit, qui trouve l'entrée du tour 2.

Erreur courante : point d'arrêt sur un contenu qui change à chaque requête

Votre prompt comporte un grand contexte système statique (blocs 1 à 5) suivi d'un bloc propre à chaque requête contenant un horodatage et le message de l'utilisateur (bloc 6). Vous définissez cache_control sur le bloc 6 :

• Requête 1 : écriture en cache au bloc 6. Le hachage inclut l'horodatage.
• Requête 2 : l'horodatage diffère, donc le hachage du préfixe au bloc 6 diffère. La rétrospection parcourt les blocs 5, 4, 3, 2 et 1, mais le système n'a jamais écrit d'entrée à aucune de ces positions. Aucun succès de cache. Vous payez une nouvelle écriture en cache à chaque requête sans jamais obtenir de lecture.

La rétrospection ne trouve pas le contenu stable situé derrière votre point d'arrêt pour le mettre en cache. Elle trouve les entrées que des requêtes antérieures ont déjà écrites, et les écritures n'ont lieu qu'aux points d'arrêt. Déplacez cache_control vers le bloc 5, le dernier bloc qui reste identique d'une requête à l'autre, et chaque requête suivante lira le préfixe mis en cache. La mise en cache automatique tombe dans le même piège : elle place le point d'arrêt sur le dernier bloc pouvant être mis en cache, qui, dans cette structure, est celui qui change à chaque requête ; utilisez donc plutôt un point d'arrêt explicite sur le bloc 5.

Point clé : placez cache_control sur le dernier bloc dont le préfixe est identique dans toutes les requêtes devant partager un cache. Dans une conversation qui s'allonge, le dernier bloc convient tant que chaque tour ajoute moins de 20 blocs : le contenu antérieur ne change jamais, donc la rétrospection de la requête suivante trouve l'écriture précédente. Pour un prompt avec un suffixe variable (horodatages, contexte propre à chaque requête, message entrant), placez le point d'arrêt à la fin du préfixe statique, et non sur le bloc variable.

Quand utiliser plusieurs points d'arrêt

Vous pouvez définir jusqu'à 4 points d'arrêt de cache si vous souhaitez :

• Mettre en cache différentes sections qui changent à des fréquences différentes (par exemple, les outils changent rarement, mais le contexte est mis à jour quotidiennement)
• Avoir un meilleur contrôle sur ce qui est exactement mis en cache
• Garantir un succès de cache lorsqu'une conversation qui s'allonge repousse votre point d'arrêt de 20 blocs ou plus au-delà de la dernière écriture en cache

Comprendre les coûts des points d'arrêt de cache

Les points d'arrêt de cache eux-mêmes n'ajoutent aucun coût. Vous n'êtes facturé que pour :

• Les écritures en cache : lorsque du nouveau contenu est écrit dans le cache (25 % de plus que les tokens d'entrée de base pour un TTL de 5 minutes)
• Les lectures du cache : lorsque du contenu mis en cache est utilisé (10 % du prix de base des tokens d'entrée, ou 2,5 % sur Claude Fable 5.1 et Claude Mythos 5.1, et 5 % sur Claude Opus 5.5)
• Les tokens d'entrée ordinaires : pour tout contenu non mis en cache

L'ajout de points d'arrêt cache_control supplémentaires n'augmente pas vos coûts ; vous payez toujours le même montant en fonction du contenu réellement mis en cache et lu. Les points d'arrêt vous permettent de contrôler quelles sections peuvent être mises en cache indépendamment.

Stratégies et considérations de mise en cache

Limitations du cache

Sur l'API Claude, Claude Platform on AWS, Google Cloud et Microsoft Foundry, la longueur minimale d'un prompt pouvant être mis en cache est de :

• 512 tokens pour Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Fable 5 et Claude Mythos 5
• 2 048 tokens pour Claude Mythos Preview et Claude Opus 4.7
• 4 096 tokens pour Claude Opus 4.6 et Claude Opus 4.5
• 1 024 tokens pour Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1 (retiré, sauf sur Bedrock et Google Cloud), Claude Opus 4 (retiré, sauf sur Google Cloud) et Claude Sonnet 4 (retiré, sauf sur Bedrock et Google Cloud)
• 4 096 tokens pour Claude Haiku 4.5
• 2 048 tokens pour Claude Haiku 3.5 (retiré, sauf sur Bedrock et Google Cloud)

Ces minimums s'appliquent sur toutes les plateformes où chaque modèle est disponible.

Les prompts plus courts ne peuvent pas être mis en cache, même s'ils sont marqués avec cache_control. Toute requête visant à mettre en cache un nombre de tokens inférieur à ce seuil est traitée sans mise en cache, et aucune erreur n'est renvoyée. Pour vérifier si un prompt a été mis en cache, consultez les champs d'utilisation de la réponse : si cache_creation_input_tokens et cache_read_input_tokens valent tous deux 0, le prompt n'a pas été mis en cache (probablement parce qu'il n'atteignait pas la longueur minimale requise).

Si votre prompt se situe juste en dessous du minimum pour votre modèle et votre plateforme, il est souvent intéressant d'étoffer le contenu mis en cache pour atteindre le seuil. Les lectures du cache coûtent nettement moins cher que les tokens d'entrée non mis en cache : atteindre le minimum peut donc réduire les coûts des prompts fréquemment réutilisés.

Pour les requêtes simultanées, notez qu'une entrée de cache ne devient disponible qu'après le début de la première réponse. Si vous avez besoin de succès de cache pour des requêtes parallèles, attendez la première réponse avant d'envoyer les requêtes suivantes.

Actuellement, « ephemeral » est le seul type de cache pris en charge ; sa durée de vie par défaut est de 5 minutes.

Ce qui peut être mis en cache

La plupart des blocs de la requête peuvent être mis en cache. Cela inclut :

• Les outils : définitions d'outils dans le tableau tools
• Les messages système : blocs de contenu dans le tableau system
• Les messages texte : blocs de contenu dans le tableau messages.content, pour les tours de l'utilisateur comme de l'assistant
• Les images et documents : blocs de contenu dans le tableau messages.content, dans les tours de l'utilisateur
• L'utilisation d'outils et les résultats d'outils : blocs de contenu dans le tableau messages.content, dans les tours de l'utilisateur comme de l'assistant

Chacun de ces éléments peut être mis en cache, soit automatiquement, soit en le marquant avec cache_control.

Ce qui ne peut pas être mis en cache

Bien que la plupart des blocs de requête puissent être mis en cache, il existe quelques exceptions :

• Les blocs de réflexion ne peuvent pas être mis en cache directement avec cache_control. Cependant, les blocs de réflexion PEUVENT être mis en cache avec d'autres contenus lorsqu'ils apparaissent dans des tours précédents de l'assistant. Lorsqu'ils sont mis en cache de cette manière, ils COMPTENT comme des tokens d'entrée lorsqu'ils sont lus depuis le cache.

• Les blocs de sous-contenu (comme les citations) ne peuvent pas eux-mêmes être mis en cache directement. Mettez plutôt en cache le bloc de niveau supérieur.

  Dans le cas des citations, les blocs de contenu de document de niveau supérieur qui servent de source aux citations peuvent être mis en cache. Cela vous permet d'utiliser efficacement la mise en cache des prompts avec les citations en mettant en cache les documents auxquels les citations feront référence.

• Les blocs de texte vides ne peuvent pas être mis en cache.

Ce qui invalide le cache

Les modifications apportées au contenu mis en cache peuvent invalider tout ou partie du cache.

Comme décrit dans Structurer votre prompt, le cache suit la hiérarchie : tools → system → messages. Les modifications à chaque niveau invalident ce niveau et tous les niveaux suivants.

Le tableau suivant indique quelles parties du cache sont invalidées par différents types de modifications. ✘ indique que le cache est invalidé, tandis que ✓ indique que le cache reste valide.

Sur les modèles qui prennent en charge les modifications d'outils en cours de conversation, l'en-tête bêta inline-tools-2026-09-15 vous permet d'ajouter un outil, ou de modifier la définition d'un outil, en cours de conversation sans modifier tools. Envoyez la définition dans un bloc tool_addition au sein d'un message système en cours de conversation et laissez tools exactement tel que vous l'avez envoyé initialement. Le préfixe en cache correspond toujours, de sorte que seul le message ajouté est traité comme une nouvelle entrée. La seule exception est un tableau tools ne contenant aucun outil non différé : dans ce cas, le premier outil défini de cette manière entraîne un échec complet du cache sur cette requête. Consultez Définir des outils dans un message.

Suivi des performances du cache

Surveillez les performances du cache à l'aide de ces champs de réponse de l'API, dans usage de la réponse (ou dans l'événement message_start en cas de streaming) :

• cache_creation_input_tokens : nombre de tokens écrits dans le cache lors de la création d'une nouvelle entrée.
• cache_read_input_tokens : nombre de tokens récupérés depuis le cache pour cette requête.
• input_tokens : nombre de tokens d'entrée qui n'ont été ni lus depuis un cache ni utilisés pour en créer un (c'est-à-dire les tokens situés après le dernier point d'arrêt de cache).

Mise en cache avec les blocs de réflexion

Lorsque vous utilisez la réflexion avec la mise en cache des prompts, les blocs de réflexion ont un comportement particulier :

Mise en cache automatique avec d'autres contenus : bien que les blocs de réflexion ne puissent pas être explicitement marqués avec cache_control, ils sont mis en cache dans le cadre du contenu de la requête lorsque vous effectuez des appels API ultérieurs avec des résultats d'outils. Cela se produit couramment lors de la « tool use » (utilisation d'outils), lorsque vous renvoyez les blocs de réflexion pour poursuivre la conversation.

Comptage des tokens d'entrée : lorsque les blocs de réflexion sont lus depuis le cache, ils comptent comme des tokens d'entrée dans vos métriques d'utilisation. Ceci est important pour le calcul des coûts et la budgétisation des tokens.

Schémas d'invalidation du cache :

• Le cache reste valide lorsque seuls des résultats d'outils sont fournis comme messages utilisateur
• Sur Opus 4.5+ et Sonnet 4.6+, les blocs de réflexion sont conservés par défaut même lorsque du contenu utilisateur autre que des résultats d'outils est ajouté, le cache reste donc valide
• Sur les modèles Opus/Sonnet antérieurs et tous les modèles Haiku, le cache est invalidé lorsque du contenu utilisateur autre que des résultats d'outils est ajouté, ce qui entraîne le retrait de tous les blocs de réflexion précédents du contexte
• Ce comportement de mise en cache se produit même sans marqueurs cache_control explicites

Pour plus de détails sur l'invalidation du cache, consultez Ce qui invalide le cache.

Exemple avec utilisation d'outils :

Request 1: User: "What's the weather in Paris?"
Response: [thinking_block_1] + [tool_use block 1]

Request 2:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]
Response: [thinking_block_2] + [text block 2]
# Request 2 caches its request content (not the response)
# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1

Request 3:
User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]
# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept

Sur les modèles Opus/Sonnet antérieurs et tous les modèles Haiku, tous les blocs de réflexion précédents sont retirés du contexte à ce stade. Sur Opus 4.5+ et Sonnet 4.6+, les blocs de réflexion antérieurs sont conservés par défaut et restent dans le préfixe mis en cache.

Pour des informations plus détaillées, consultez Réflexion et mise en cache des prompts.

Stockage et partage du cache

• Isolation des organisations et des espaces de travail : les caches sont isolés entre les organisations. Des organisations différentes ne partagent jamais de caches, même si elles utilisent des prompts identiques. Les caches sont également isolés par espace de travail au sein d'une organisation sur l'API Claude, Claude Platform on AWS et Microsoft Foundry ; Bedrock et Google Cloud utilisent uniquement une isolation au niveau de l'organisation.

• Correspondance exacte : les succès de cache nécessitent des segments de prompt identiques à 100 %, y compris l'ensemble du texte et des images jusqu'au bloc marqué avec le contrôle de cache inclus.

• Génération des tokens de sortie : la mise en cache des prompts n'a aucun effet sur la génération des tokens de sortie. La réponse que vous recevez est identique à celle que vous obtiendriez sans mise en cache des prompts.

Bonnes pratiques pour une mise en cache efficace

Pour optimiser les performances de la mise en cache des prompts :

• Commencez par la mise en cache automatique pour les conversations multi-tours. Elle gère automatiquement les points d'arrêt.
• Utilisez des points d'arrêt explicites au niveau des blocs lorsque vous devez mettre en cache différentes sections ayant des fréquences de modification différentes.
• Mettez en cache le contenu stable et réutilisable, comme les instructions système, les informations de fond, les contextes volumineux ou les définitions d'outils fréquentes.
• Placez le contenu mis en cache au début du prompt pour de meilleures performances.
• Utilisez les points d'arrêt de cache de manière stratégique pour séparer les différentes sections de préfixe pouvant être mises en cache.
• Placez le point d'arrêt sur le dernier bloc qui reste identique d'une requête à l'autre. Pour un prompt avec un préfixe statique et un suffixe variable (horodatages, contexte propre à chaque requête, message entrant), il s'agit de la fin du préfixe, et non du bloc variable.
• Analysez régulièrement les taux de succès de cache et ajustez votre stratégie si nécessaire.

Optimisation pour différents cas d'usage

Adaptez votre stratégie de mise en cache des prompts à votre scénario :

• Agents conversationnels : réduisez les coûts et la « latency » (latence) pour les conversations prolongées, en particulier celles comportant de longues instructions ou des documents téléversés.
• Assistants de programmation : améliorez l'autocomplétion et les questions-réponses sur la base de code en conservant dans le prompt les sections pertinentes ou une version résumée de la base de code.
• Traitement de documents volumineux : intégrez dans votre prompt des contenus longs et complets, y compris des images, sans augmenter la latence de réponse.
• Ensembles d'instructions détaillés : partagez des listes étendues d'instructions, de procédures et d'exemples pour affiner les réponses de Claude. Les développeurs incluent souvent un ou deux exemples dans le prompt, mais avec la mise en cache des prompts, vous pouvez obtenir des performances encore meilleures en incluant plus de 20 exemples variés de réponses de haute qualité.
• Utilisation d'outils agentique : améliorez les performances dans les scénarios impliquant plusieurs appels d'outils et des modifications de code itératives, où chaque étape nécessite généralement un nouvel appel API.
• Dialoguer avec des livres, des articles, de la documentation, des transcriptions de podcasts et d'autres contenus longs : donnez vie à n'importe quelle base de connaissances en intégrant le ou les documents entiers dans le prompt et en permettant aux utilisateurs de lui poser des questions.

Résolution des problèmes courants

Si vous constatez un comportement inattendu :

• Assurez-vous que les sections mises en cache sont identiques d'un appel à l'autre. Pour les points d'arrêt explicites, vérifiez que les marqueurs cache_control se trouvent aux mêmes emplacements
• Vérifiez que les appels sont effectués pendant la durée de vie du cache (5 minutes par défaut)
• Vérifiez que tool_choice, l'utilisation d'images, la configuration de réflexion et output_config.effort restent cohérents entre les appels
• Vérifiez que vous mettez en cache au moins le nombre minimal de tokens pour votre modèle et votre plateforme (consultez Limitations du cache)
• Confirmez que votre point d'arrêt se trouve sur un bloc qui reste identique d'une requête à l'autre. Les écritures de cache n'ont lieu qu'au point d'arrêt, et si ce bloc change (horodatages, contexte propre à chaque requête, message entrant), le hachage du préfixe ne correspond jamais. La rétrospection ne trouve pas le contenu stable situé derrière le point d'arrêt ; elle ne trouve que les entrées que des requêtes antérieures ont écrites à leurs propres points d'arrêt
• Vérifiez que les clés de vos blocs de contenu tool_use ont un ordre stable, car certains langages (par exemple, Swift, Go) rendent aléatoire l'ordre des clés lors de la conversion JSON, ce qui casse les caches
• Utilisez les diagnostics de cache pour que l'API compare des requêtes consécutives et indique quelle partie du prompt a divergé

Durée de cache d'une heure

Si vous trouvez que 5 minutes est trop court, Anthropic propose également une durée de cache d'une heure moyennant un coût supplémentaire.

Pour utiliser le cache étendu, incluez ttl dans la définition de cache_control comme ceci :

"cache_control": {
  "type": "ephemeral",
  "ttl": "1h"
}

La réponse inclut des informations détaillées sur le cache, comme suit :

{
  "usage": {
    "input_tokens": 2048,
    "cache_read_input_tokens": 1800,
    "cache_creation_input_tokens": 248,
    "output_tokens": 503,

    "cache_creation": {
      "ephemeral_5m_input_tokens": 148,
      "ephemeral_1h_input_tokens": 100
    }
  }
}

Notez que le champ actuel cache_creation_input_tokens est égal à la somme des valeurs de l'objet cache_creation.

Si vous constatez des écritures ephemeral_5m_input_tokens que vous n'avez pas demandées lors de l'utilisation d'outils serveur tels que la recherche web, consultez Utilisation d'outils avec la mise en cache des prompts.

Quand utiliser le cache d'une heure

Si vous avez des prompts utilisés à une cadence régulière (c'est-à-dire des invites système utilisées plus fréquemment que toutes les 5 minutes), continuez à utiliser le cache de 5 minutes, car celui-ci continuera d'être actualisé sans frais supplémentaires.

Le cache d'une heure est particulièrement adapté aux scénarios suivants :

• Lorsque vous avez des prompts susceptibles d'être utilisés moins fréquemment que toutes les 5 minutes, mais plus fréquemment que toutes les heures. Par exemple, lorsqu'un agent secondaire agentique prendra plus de 5 minutes, ou lorsque vous stockez une longue conversation avec un utilisateur et que vous vous attendez généralement à ce que cet utilisateur ne réponde pas dans les 5 prochaines minutes.
• Lorsque la latence est importante et que vos prompts de suivi peuvent être envoyés au-delà de 5 minutes.
• Lorsque vous souhaitez améliorer l'utilisation de votre limite de débit, car les succès de cache ne sont pas décomptés de votre limite de débit.

Mélanger différents TTL

Vous pouvez utiliser à la fois des contrôles de cache d'une heure et de 5 minutes dans la même requête, mais avec une contrainte importante : les entrées de cache ayant un TTL plus long doivent apparaître avant celles ayant un TTL plus court (c'est-à-dire qu'une entrée de cache d'une heure doit apparaître avant toute entrée de cache de 5 minutes).

Lorsque vous mélangez des TTL, l'API détermine trois positions de facturation dans votre prompt :

1. Position A : le nombre de tokens au succès de cache le plus élevé (ou 0 en l'absence de succès).
2. Position B : le nombre de tokens au bloc cache_control d'une heure le plus élevé après A (ou égal à A s'il n'en existe aucun).
3. Position C : le nombre de tokens au dernier bloc cache_control.

Vous serez facturé pour :

1. Les tokens de lecture du cache pour A.
2. Les tokens d'écriture en cache d'une heure pour (B - A).
3. Les tokens d'écriture en cache de 5 minutes pour (C - B).

Voici trois exemples. Ce schéma représente les tokens d'entrée de 3 requêtes, chacune ayant des « cache hits » (succès de cache) et des « cache misses » (échecs de cache) différents. Chacune a par conséquent une tarification calculée différente, indiquée dans les encadrés colorés.

Préchauffage du cache

Le « cache pre-warming » (préchauffage du cache) vous permet de charger votre invite système ou vos définitions d'outils dans le cache des prompts avant qu'un utilisateur ne déclenche une requête réelle. Cela supprime la pénalité de « latency » (latence) due à un « cache miss » (échec de cache) lors de la première interaction de l'utilisateur. Le « time-to-first-token » (délai avant le premier token), ou TTFT, est ainsi réduit pour les applications sensibles à la latence.

Fonctionnement

Définissez max_tokens: 0 dans votre requête. L'API lit votre prompt dans le modèle et écrit le cache à chaque point d'arrêt cache_control, puis renvoie immédiatement une réponse sans générer de sortie. La réponse contient un tableau content vide, stop_reason: "max_tokens" et un bloc usage entièrement renseigné.

Placez le point d'arrêt cache_control sur le dernier bloc partagé avec la requête suivante (généralement votre invite système ou vos définitions d'outils), et non sur le message utilisateur de substitution. Sinon, l'entrée de cache est associée au message de substitution et la requête suivante ne l'atteindra pas. Utilisez également la même configuration de réflexion et le même output_config.effort que vos requêtes suivantes : ces valeurs sont intégrées au prompt (voir Ce qui invalide le cache), de sorte qu'un préchauffage avec une configuration différente peut écrire une entrée que votre trafic réel n'atteindra jamais. Cela implique d'utiliser un point d'arrêt de cache explicite plutôt que la mise en cache automatique, puisque la mise en cache automatique place le point d'arrêt sur le dernier bloc, qui est ici le message de substitution. Le message utilisateur de substitution peut être n'importe quelle chaîne contenant des caractères autres que des espaces (les exemples ici utilisent "warmup") ; son contenu est lu par le modèle mais ne reçoit jamais de réponse.

client = anthropic.Anthropic()

# Lancez ceci avant l'arrivée des utilisateurs pour préchauffer le cache partagé de l'invite système.
prewarm = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=0,
    system=[
        {
            "type": "text",
            "text": "You are an expert software engineer with deep knowledge of distributed systems...",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason)  # "max_tokens"
print(prewarm.content)  # []
print(prewarm.usage)

L'API renvoie un tableau content vide :

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-5-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "cache_creation_input_tokens": 5120,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 5120,
      "ephemeral_1h_input_tokens": 0
    },
    "iterations": [
      {
        "input_tokens": 8,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 5120,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 5120,
          "ephemeral_1h_input_tokens": 0
        },
        "type": "message"
      }
    ],
    "output_tokens": 0,
    "service_tier": "standard",
    "inference_geo": "global"
  }
}

Modèle d'utilisation typique

Lancez une requête de préchauffage au démarrage de votre application (ou à intervalles planifiés), puis envoyez les véritables requêtes des utilisateurs une fois le préchauffage terminé :

client = anthropic.Anthropic()

SYSTEM_PROMPT = [
    {
        "type": "text",
        "text": "You are an expert software engineer with deep knowledge of distributed systems...",
        "cache_control": {"type": "ephemeral"},
    }
]


def prewarm_cache() -> None:
    """Call this at application startup or on a scheduled interval."""
    client.messages.create(
        model="claude-opus-5-5",
        max_tokens=0,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": "warmup"}],
    )


def respond(user_message: str) -> anthropic.types.Message:
    """The real user request; benefits from a warm cache."""
    return client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": user_message}],
    )


# Préchauffez le cache avant l'arrivée de tout trafic utilisateur.
prewarm_cache()

# Plus tard, lorsque l'utilisateur envoie un message, le préfixe du « system prompt » (invite système) est déjà en cache.
response = respond("How do I implement a binary search tree?")
for block in response.content:
    if block.type == "text":
        print(block.text)

Gardez à l'esprit que le TTL du cache s'applique toujours. Pour le cache par défaut de 5 minutes, envoyez une nouvelle requête de préchauffage au moins toutes les 5 minutes pour maintenir le cache chaud. Pour des intervalles plus longs entre les requêtes des utilisateurs, utilisez plutôt la durée de cache d'une heure.

Limitations

Une requête max_tokens: 0 est rejetée avec une erreur invalid_request_error si l'un des éléments suivants est défini. Chacun implique en effet une sortie qu'un budget de zéro token ne peut pas produire :

• stream: true
• Réflexion étendue (thinking.type: "enabled")
• Sorties structurées (output_config.format)
• tool_choice de type {"type": "tool", ...} ou {"type": "any"}

max_tokens: 0 est également rejeté dans une requête Message Batches. Le préchauffage vise à réduire le délai avant le premier token, ce qui ne concerne pas le traitement par lots. De plus, une entrée de cache écrite pendant un traitement par lots expirerait probablement avant l'exécution de la requête suivante.

Remplacer la solution de contournement max_tokens=1

Avant l'arrivée de max_tokens: 0, certaines applications utilisaient des appels de préchauffage avec max_tokens: 1 pour obtenir le même effet. L'approche max_tokens: 0 est préférable : aucune sortie n'est produite, il n'y a donc pas de réponse d'un seul token à ignorer. Aucun token de sortie n'est facturé et l'intention de la requête est sans ambiguïté.

Exemples de mise en cache des prompts

Pour vous aider à démarrer avec la mise en cache des prompts, le cookbook sur la mise en cache des prompts fournit des exemples détaillés et des bonnes pratiques.

Les extraits de code suivants présentent divers modèles de mise en cache des prompts. Ces exemples montrent comment implémenter la mise en cache dans différents scénarios, afin de vous aider à comprendre les applications pratiques de cette fonctionnalité :

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents.",
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?",
        }
    ],
)
print(response.usage.model_dump_json())

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": { "location": { "type": "string" } },
        "required": ["location"]
      }
    },
    {
      "name": "get_time",
      "description": "Get the current time in a given time zone",
      "input_schema": {
        "type": "object",
        "properties": { "timezone": { "type": "string" } },
        "required": ["timezone"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        # ...longue conversation jusqu'ici
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ],
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Good to know."},
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"},
                },
            ],
        },
    ],
)
print(response.usage.model_dump_json())

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "Search query"}
                },
                "required": ["query"],
            },
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {"type": "string", "description": "Document ID"}
                },
                "required": ["doc_id"],
            },
            "cache_control": {"type": "ephemeral"},
        },
    ],
    system=[
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"},
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"},
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"},
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
                }
            ],
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
    ],
)
print(response.usage.model_dump_json())

Conservation des données

La mise en cache des prompts (automatique comme explicite) est éligible ZDR. Anthropic ne stocke pas le texte brut de vos prompts ni les réponses de Claude.

Les représentations du cache KV (clé-valeur) et les empreintes cryptographiques du contenu mis en cache sont conservées uniquement en mémoire et ne sont pas stockées au repos. Les entrées de cache ont une durée de vie minimale de 5 minutes (standard) ou d'une heure (étendue). Elles sont ensuite supprimées rapidement, mais pas immédiatement. Les entrées de cache sont isolées entre organisations. Sur l'API Claude, Claude Platform on AWS et Microsoft Foundry, elles sont aussi isolées entre les espaces de travail d'une même organisation.

Pour connaître l'éligibilité ZDR de l'ensemble des fonctionnalités, consultez API et conservation des données.

FAQ

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

client.beta.prompt_caching.messages.create(**params)

client.messages.create(**params)

client.beta.promptCaching.messages.create(/* ... */);

client.messages.create(/* ... */);