Mise en cache des prompts

La 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 point d'arrêt de cache au dernier bloc pouvant être mis en cache et le déplace vers l'avant à 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 sur ce qui est exactement 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",
    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 avec 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à mis en cache à partir d'une requête récente.
2. S'il est trouvé, il utilise la version mise en cache, réduisant ainsi le temps de traitement et les coûts.
3. Sinon, il traite le prompt complet et met en cache le préfixe une fois 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 multi-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 prend 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 introduit une nouvelle structure tarifaire. Le tableau suivant indique le prix par million de tokens pour chaque modèle pris en charge :



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",
    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 de 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 utilise l'un des 4 emplacements de points 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",
  "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 recherche arrière 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 contrôle plus fin sur 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 sur ce qui est exactement 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 pour la mise 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 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 de cache se produisent 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, modifier 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 de cache recherchent en arrière les entrées que des requêtes antérieures ont écrites. À chaque requête, le système calcule le hachage du préfixe à votre point d'arrêt et vérifie s'il existe une entrée de cache correspondante. Si aucune n'existe, il remonte bloc par bloc, 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, pas du contenu stable.

3. La fenêtre de recherche arrière 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, le cas échéant).

Exemple : recherche arrière dans une conversation croissante

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, donc le système remonte jusqu'au bloc 10 et trouve l'entrée du tour 1. Correspondance de cache au bloc 10 ; le système traite uniquement les blocs 11 à 15 à nouveau 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 correspondance de cache. Ajouter un deuxième point d'arrêt au bloc 15 démarre une deuxième fenêtre de recherche arrière à cet endroit, qui trouve l'entrée du tour 2.

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

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

• Requête 1 : écriture de 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 recherche arrière parcourt les blocs 5, 4, 3, 2 et 1, mais le système n'a jamais écrit d'entrée à aucune de ces positions. Aucune correspondance de cache. Vous payez pour une nouvelle écriture de cache à chaque requête et n'obtenez jamais de lecture.

La recherche arrière ne trouve pas de contenu stable derrière votre point d'arrêt pour le mettre en cache. Elle trouve des entrées que des requêtes antérieures ont déjà écrites, et les écritures se produisent uniquement aux points d'arrêt. Déplacez cache_control vers le bloc 5, le dernier bloc qui reste identique entre les requêtes, 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é à retenir : placez cache_control sur le dernier bloc dont le préfixe est identique entre les requêtes que vous souhaitez faire partager un cache. Dans une conversation croissante, le dernier bloc fonctionne tant que chaque tour ajoute moins de 20 blocs : le contenu antérieur ne change jamais, donc la recherche arrière de la requête suivante trouve l'écriture précédente. Pour un prompt avec un suffixe variable (horodatages, contexte par requête, message entrant), placez le point d'arrêt à la fin du préfixe statique, pas 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 plus de contrôle sur ce qui est exactement mis en cache
• Garantir une correspondance de cache lorsqu'une conversation croissante pousse votre point d'arrêt à 20 blocs ou plus au-delà de la dernière écriture de 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 êtes facturé uniquement pour :

• Les écritures de 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 de cache : lorsque du contenu mis en cache est utilisé (10 % du prix de base des tokens d'entrée)
• Les tokens d'entrée normaux : pour tout contenu non mis en cache

Ajouter plus de points d'arrêt cache_control 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 donnent le contrôle sur les sections qui 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 de prompt pouvant être mise en cache est :

• 512 tokens pour 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 chaque plateforme 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 moins que ce nombre de tokens sera 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 sont 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, étendre le contenu mis en cache pour atteindre le seuil est souvent rentable. Les lectures de cache coûtent nettement moins cher que les tokens d'entrée non mis en cache, donc atteindre le minimum peut réduire les coûts pour les prompts fréquemment réutilisés.

Pour les requêtes concurrentes, 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 correspondances 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, qui a par défaut une durée de vie 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 :

• Outils : définitions d'outils dans le tableau tools
• Messages système : blocs de contenu dans le tableau system
• Messages texte : blocs de contenu dans le tableau messages.content, pour les tours utilisateur et assistant
• Images et documents : blocs de contenu dans le tableau messages.content, dans les tours utilisateur
• Utilisation d'outils et résultats d'outils : blocs de contenu dans le tableau messages.content, dans les tours utilisateur et assistant

Chacun de ces éléments peut être mis en cache, soit automatiquement, soit en les 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 d'assistant précédents. 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 sous-blocs de contenu (comme les citations) eux-mêmes ne peuvent pas ê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ériel 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 que les citations référenceront.

• 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 montre 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.



Suivi des performances du cache

Surveillez les performances du cache à l'aide de ces champs de réponse de l'API, dans usage dans la réponse (ou l'événement message_start si vous utilisez le 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 le 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 des 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 préservés par défaut même lorsque du contenu utilisateur autre que des résultats d'outils est ajouté, donc le cache reste 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 la suppression 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 supprimé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 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 par organisation et workspace : 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 workspace 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 correspondances de cache nécessitent des segments de prompt 100 % identiques, y compris tout le texte et les images jusqu'au bloc marqué avec cache control inclus.

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



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 avec des fréquences de changement différentes.
• Mettez en cache du contenu stable et réutilisable comme les instructions système, les informations de référence, 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 différentes sections de préfixe pouvant être mises en cache.
• Placez le point d'arrêt sur le dernier bloc qui reste identique entre les requêtes. Pour un prompt avec un préfixe statique et un suffixe variable (horodatages, contexte par requête, message entrant), il s'agit de la fin du préfixe, pas du bloc variable.
• Analysez régulièrement les taux de correspondance 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 latence pour les conversations prolongées, en particulier celles comportant de longues instructions ou des documents téléversés.
• Assistants de codage : 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 : incorporez 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 pour 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, articles, documentation, transcriptions de podcasts et 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 rencontrez un comportement inattendu :

• Assurez-vous que les sections mises en cache sont identiques entre les appels. Pour les points d'arrêt explicites, vérifiez que les marqueurs cache_control sont aux mêmes emplacements
• Vérifiez que les appels sont effectués dans 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
• Validez que vous mettez en cache au moins le nombre minimal de tokens pour votre modèle et votre plateforme (voir Limitations du cache)
• Confirmez que votre point d'arrêt se trouve sur un bloc qui reste identique entre les requêtes. Les écritures de cache se produisent uniquement au point d'arrêt, et si ce bloc change (horodatages, contexte par requête, message entrant), le hachage du préfixe ne correspond jamais. La recherche arrière ne trouve pas de contenu stable derrière le point d'arrêt ; elle trouve uniquement des 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) randomisent 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 signale quelle partie du prompt a divergé



Durée de cache de 1 heure

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

Pour utiliser le cache étendu, incluez ttl dans la définition 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 cache_creation_input_tokens actuel est égal à la somme des valeurs dans l'objet cache_creation.

Si vous voyez 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 de 1 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 à être actualisé sans frais supplémentaires.

Le cache de 1 heure est le mieux 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 sous-agent agentique prendra plus de 5 minutes, ou lors du stockage d'une longue conversation de chat avec un utilisateur dont vous prévoyez généralement qu'il ne répondra 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 correspondances de cache ne sont pas déduites de votre limite de débit.



Mélanger différents TTL

Vous pouvez utiliser à la fois 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 avec un TTL plus long doivent apparaître avant les TTL plus courts (c'est-à-dire qu'une entrée de cache de 1 heure doit apparaître avant toute entrée de cache de 5 minutes).

Lors du mélange de TTL, l'API détermine trois emplacements de facturation dans votre prompt :

1. Position A : le nombre de tokens à la correspondance de cache la plus élevée (ou 0 s'il n'y a pas de correspondance).
2. Position B : le nombre de tokens au bloc cache_control de 1 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 de cache pour A.
2. Les tokens d'écriture de cache de 1 heure pour (B - A).
3. Les tokens d'écriture de cache de 5 minutes pour (C - B).

Voici trois exemples. Ceci représente les tokens d'entrée de 3 requêtes, chacune ayant des correspondances et des échecs de cache différents. Chacune a une tarification calculée différente, indiquée dans les cases colorées, en conséquence.



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 de prompts avant qu'un utilisateur ne déclenche une requête réelle. Cela élimine la pénalité de latence due à l'échec de cache lors de la première interaction utilisateur, réduisant le « time-to-first-token » (temps 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 retourne immédiatement 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 de suivi (généralement votre invite système ou vos définitions d'outils), et non sur le message utilisateur servant de substitut. Sinon, l'entrée de cache est associée au substitut et la requête de suivi ne la trouvera pas. Utilisez également la même configuration de réflexion et la même valeur output_config.effort que vos requêtes de suivi : ces valeurs sont rendues dans le prompt (voir Ce qui invalide le cache), donc 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 substitut. Le message utilisateur servant de substitut peut être n'importe quelle chaîne contenant des caractères autres que des espaces (les exemples ici utilisent "warmup") ; son contenu est lu dans 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",
    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 retourne un tableau content vide :

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [],
  "model": "claude-opus-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"
  }
}



Schéma d'utilisation typique

Lancez une requête de préchauffage au démarrage de votre application (ou à intervalle planifié), puis envoyez les requêtes utilisateur réelles 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",
        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",
        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à mis 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 actif. Pour des intervalles plus longs entre les requêtes utilisateur, utilisez plutôt la durée de cache d'une heure.



Limitations

Une requête avec 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 avec {"type": "tool", ...} ou {"type": "any"}

max_tokens: 0 est également rejeté à l'intérieur d'une requête Message Batches. Le préchauffage cible le délai avant le premier token, ce 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 de suivi.



Remplacement du contournement max_tokens=1

Avant que max_tokens: 0 ne soit disponible, 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 schémas de mise en cache des prompts. Ces exemples montrent comment implémenter la mise en cache dans différents scénarios, vous aidant à comprendre les applications pratiques de cette fonctionnalité :



Conservation des données

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

Les représentations de 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 de manière persistante. Les entrées mises en cache ont une durée de vie minimale de 5 minutes (standard) ou d'une heure (étendue), après quoi elles sont supprimées rapidement, bien que pas immédiatement. Les entrées de cache sont isolées entre les organisations et, sur l'API Claude, Claude Platform sur AWS et Microsoft Foundry, entre les espaces de travail au sein d'une organisation.

Pour l'éligibilité ZDR sur l'ensemble des fonctionnalités, consultez API et conservation des données.



FAQ