Mise en cache des prompts

Le « prompt caching » (mise en cache des prompts) optimise votre utilisation de l’API en permettant à l’API 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. Idéal 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 un contrôle précis de ce qui est mis en cache.

La manière 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 à partir d’une requête récente.
2. S’il est trouvé, il utilise la version mise en cache, ce qui réduit le temps de traitement et les coûts.
3. Sinon, il traite le prompt complet et met en cache le préfixe 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 fond
• Les tâches répétitives avec des instructions constantes
• Les longues conversations multi-tours

Par défaut, le cache a une durée de vie de 5 minutes. Le cache est rafraîchi 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 diffusée en streaming, une requête de suivi qui réutilise le même préfixe mis en cache doit démarrer dans un délai d’environ 1 minute après la fin de cette réponse.

Tarification

La mise en cache des prompts dispose de sa propre tarification. Le tableau suivant indique le prix par million de tokens pour chaque modèle pris en charge :

Modèle	Jetons de base		Mémorisation des requêtes
Nom	Entrée	Sortie	Écritures 5 min	Écritures 1 h	Accès au cache et actualisations
Claude Fable 5.2For demanding reasoning and long-horizon agentic work	8 $US / MTok	40 $US / MTok	10 $US / MTok	16 $US / MTok	0,20 $US / MTok1
Claude Opus 5.5For long-running agentic coding and knowledge work	4 $US / MTok	20 $US / MTok	5 $US / MTok	8 $US / MTok	0,20 $US / MTok2
Claude Sonnet 5.5The best combination of speed and intelligence	2 $US / MTok	10 $US / MTok	2,50 $US / MTok	4 $US / MTok	0,10 $US / MTok2
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing	0,10 $US / MTokpour les requêtes jusqu’à 100 000 jetons	0,50 $US / MTok	0,125 $US / MTok	0,20 $US / MTok	0,01 $US / MTok
	0,50 $US / MTokpour les requêtes de plus de 100 000 jetons	2,50 $US / MTok	0,625 $US / MTok	1 $US / MTok	0,05 $US / MTok
Modèles supplémentaires
Claude Mythos 5.2	8 $US / MTok	40 $US / MTok	10 $US / MTok	16 $US / MTok	0,20 $US / MTok1
Claude Fable 5.1	10 $US / MTok	50 $US / MTok	12,50 $US / MTok	20 $US / MTok	0,25 $US / MTok1
Claude Mythos 5.1	10 $US / MTok	50 $US / MTok	12,50 $US / MTok	20 $US / MTok	0,25 $US / MTok1
Claude Fable 5	10 $US / MTok	50 $US / MTok	12,50 $US / MTok	20 $US / MTok	1 $US / MTok
Claude Mythos 5	10 $US / MTok	50 $US / MTok	12,50 $US / MTok	20 $US / MTok	1 $US / MTok
Claude Opus 5	5 $US / MTok	25 $US / MTok	6,25 $US / MTok	10 $US / MTok	0,50 $US / MTok
Claude Opus 4.8	5 $US / MTok	25 $US / MTok	6,25 $US / MTok	10 $US / MTok	0,50 $US / MTok
Claude Opus 4.7	5 $US / MTok	25 $US / MTok	6,25 $US / MTok	10 $US / MTok	0,50 $US / MTok
Claude Opus 4.6	5 $US / MTok	25 $US / MTok	6,25 $US / MTok	10 $US / MTok	0,50 $US / MTok
Claude Opus 4.5	5 $US / MTok	25 $US / MTok	6,25 $US / MTok	10 $US / MTok	0,50 $US / MTok
Claude Opus 4.1	15 $US / MTok	75 $US / MTok	18,75 $US / MTok	30 $US / MTok	1,50 $US / MTok
Claude Opus 4	15 $US / MTok	75 $US / MTok	18,75 $US / MTok	30 $US / MTok	1,50 $US / MTok
Claude Sonnet 5	2 $US / MTok	10 $US / MTok	2,50 $US / MTok	4 $US / MTok	0,20 $US / MTok
Claude Sonnet 4.6	3 $US / MTok	15 $US / MTok	3,75 $US / MTok	6 $US / MTok	0,30 $US / MTok
Claude Sonnet 4.5	3 $US / MTok	15 $US / MTok	3,75 $US / MTok	6 $US / MTok	0,30 $US / MTok
Claude Sonnet 4	3 $US / MTok	15 $US / MTok	3,75 $US / MTok	6 $US / MTok	0,30 $US / MTok
Claude Haiku 4.5	1 $US / MTok	5 $US / MTok	1,25 $US / MTok	2 $US / MTok	0,10 $US / MTok

^{1 Les accès au cache et les actualisations du cache pour Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1 et Claude Mythos 5.1 sont facturés 0,025x le prix de base en entrée.}

^{2 Les accès au cache et les actualisations du cache pour Claude Opus 5.5 et Claude Sonnet 5.5 sont facturés 0,05x le prix de base en entrée.}

^{Tous les autres modèles utilisent le multiplicateur standard de 0,1x.}

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 manière 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 TTL de 5 minutes. Vous pouvez spécifier un TTL d’1 heure à 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 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 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 limites

• 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. Cela 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 où 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 trouve automatiquement le plus long préfixe 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 pas d’entrées pour une position antérieure. Comme le hachage est cumulatif, couvrant tout jusqu’au point d’arrêt inclus, la modification de n’importe quel bloc situé au 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 pour trouver les entrées écrites par les 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 pour chaque 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 série de blocs tool_use consécutifs compte comme une seule position, tout comme une série de blocs tool_result consécutifs, de sorte qu’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. 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 et n’obtenez jamais 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 sur 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 présente le même problème : 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.

À retenir : Placez cache_control sur le dernier bloc dont le préfixe est identique pour 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 de ce qui est 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 pour cent 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 pour cent du prix de base des tokens d’entrée, avec des exceptions par modèle)
• 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 effectivement 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, Claude Models on Google Cloud (Google managed) et Microsoft Foundry, la longueur minimale de prompt pouvant être mise en cache est de :

• 512 tokens pour Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, Claude Mythos 5 et Claude Haiku 5.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 (déprécié), Claude Opus 4.1 (retiré, sauf sur Claude Models on Google Cloud (Google managed) et Bedrock), Claude Opus 4 (retiré, sauf sur Claude Models on Google Cloud (Google managed)) et Claude Sonnet 4 (retiré, sauf sur Claude Models on Google Cloud (Google managed) et Bedrock)
• 4 096 tokens pour Claude Haiku 4.5

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 demande de mise en cache de moins de ce nombre de tokens 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 est juste en dessous du minimum pour votre modèle et votre plateforme, il est souvent intéressant d’étendre 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 pour les 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, avec une durée de vie par défaut de 5 minutes.

Ce qui peut être mis en cache

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

• 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 SONT comptabilisés comme tokens d’entrée lorsqu’ils sont lus depuis le cache.

• Les sous-blocs de contenu (tels que 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 matériau source pour les 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 font référence.

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

Ce qui invalide le cache

Les modifications du 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 dans un message système en cours de conversation et laissez tools exactement tel que vous l’avez envoyé la première fois. Le préfixe mis 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é, où le premier outil défini de cette manière coûte un échec de cache complet 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 pas été lus depuis un cache ni utilisés pour en créer un (c’est-à-dire les tokens 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 l’utilisation d’outils, lorsque vous renvoyez les blocs de réflexion pour poursuivre la conversation.

Comptabilisation des tokens d’entrée : Lorsque les blocs de réflexion sont lus depuis le cache, ils sont comptabilisés comme 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+, Sonnet 4.6+ et Haiku 5.5, 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 les modèles Haiku jusqu’à Claude Haiku 4.5, 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]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)

Sur les modèles Opus/Sonnet antérieurs et les modèles Haiku jusqu’à Claude Haiku 4.5, tous les blocs de réflexion précédents sont retirés du contexte à ce stade. Sur Opus 4.5+, Sonnet 4.6+ et Haiku 5.5, les blocs de réflexion antérieurs sont conservés par défaut et restent partie intégrante du 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 ; Claude Models on Google Cloud (Google managed) et Bedrock 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 tout le texte et toutes les 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 la 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 grands contextes 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’utilisation

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

• Agents conversationnels : réduisez les coûts et la 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 les sections pertinentes ou une version résumée de la base de code dans le prompt.
• Traitement de documents volumineux : intégrez du matériel long complet, y compris des images, dans votre prompt 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.
• Livres, articles, documentation, transcriptions de podcasts et autres contenus longs : rendez n’importe quelle base de connaissances interactive en intégrant le ou les documents complets dans le prompt et en permettant aux utilisateurs de lui poser des questions.

Résolution des problèmes courants

En cas de 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 la réflexion et output_config.effort restent cohérents entre les appels.
• Validez 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 en 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 l’ordre des clés aléatoire lors de la conversion JSON, ce qui casse les caches.
• Utilisez les diagnostics de cache pour demander à l’API de comparer des requêtes consécutives et d’indiquer quelle partie du prompt a divergé.

Durée de cache d’1 heure

Si vous trouvez que 5 minutes est trop court, Anthropic propose également une durée de cache d’1 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
    }
  }
}

Le champ 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 Les résultats des outils serveur sont mis en cache automatiquement.

Quand utiliser le cache d’1 heure

Si vous utilisez un prompt à une cadence régulière (par exemple, une invite système que vous envoyez plus fréquemment que toutes les 5 minutes), continuez à utiliser le cache de 5 minutes, car celui-ci continue d’être rafraîchi sans frais supplémentaires.

Le cache d’1 heure est le plus 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 prend plus de 5 minutes, ou lorsque vous stockez une longue conversation de chat 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.

Combiner différentes TTL

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

Lorsque vous combinez des TTL, l’API Claude détermine trois positions de facturation dans votre prompt :

1. Position A : le nombre de tokens au niveau du dernier « cache hit » (succès de cache) dans votre prompt (ou 0 s’il n’y a aucun succès).
   • Un succès de cache sur une entrée mise en cache avec une TTL de 5 minutes n’est pas retenu si un bloc cache_control dont la TTL est de 1 heure, situé plus loin que cette entrée dans le prompt, est un échec de cache.
   • Une requête qui lit une entrée mise en cache avec une TTL de 5 minutes fait redémarrer la durée de vie de 5 minutes de cette entrée, même si la requête définit désormais "ttl": "1h".
2. Position B : le nombre de tokens au niveau du dernier bloc cache_control dont la TTL est de 1 heure, situé plus loin que A dans le prompt (ou égal à A s’il n’en existe aucun).
3. Position C : le nombre de tokens au niveau du dernier bloc cache_control.

Vous êtes facturé pour :

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

Voici trois exemples de requêtes, chacune ayant des succès et des échecs de cache différents. Chacune a un prix calculé différent, indiqué dans les encadrés.

Préchauffage du cache

Le 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 véritable requête. Cela peut réduire la pénalité de latence liée à l’échec de cache lors de la première interaction de l’utilisateur, diminuant ainsi le « time-to-first-token » (délai jusqu’au premier token), ou TTFT, 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, car 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 comportant un contenu autre 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()

# Exécutez 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

Effectuez 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 de l'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 la 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 de 1 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, car chacun implique 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 le délai jusqu’au premier token, qui ne s’applique pas au traitement par lots, et une entrée de cache écrite pendant le traitement par lots expirerait probablement avant l’exécution de la requête suivante.

Remplacer la solution de contournement max_tokens=1

Certaines applications envoient des requêtes max_tokens: 1 pour préchauffer le cache. Privilégiez max_tokens: 0 lorsque la requête le permet : aucune sortie n’est produite, il n’y a donc aucune 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 « prompt caching » (mise en cache des prompts), la recette de mise en cache des prompts du Claude Cookbook 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, pour 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 à la 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 hachages cryptographiques du contenu mis en cache sont conservés uniquement en mémoire et ne sont pas stockés au repos. Les entrées mises en cache ont une durée de vie minimale de 5 minutes (standard) ou de 1 heure (étendue), après quoi elles sont supprimées rapidement, mais pas immédiatement. Les entrées de cache sont isolées entre les organisations et, sur l’API Claude, Claude Platform on AWS et Microsoft Foundry, entre les espaces de travail d’une même organisation.

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(/* ... */);

Disponibilité