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 point de rupture de cache au dernier bloc pouvant être mis en cache et le fait avancer au fur et à 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 de rupture 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 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.



Comment fonctionne 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 de rupture 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 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 avec 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 actualisé sans coût supplémentaire chaque fois que le contenu mis en cache est utilisé.



Tarification

La mise en cache des prompts introduit une nouvelle structure tarifaire. Le tableau suivant montre 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 de rupture 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())



Comment fonctionne la mise en cache automatique dans les conversations multi-tours

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

Le point de rupture 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 au fur et à mesure que la conversation s'allonge.



Prise en charge des TTL

Par défaut, la mise en cache automatique utilise un TTL de 5 minutes. Vous pouvez spécifier un TTL d'une 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 de rupture de cache explicites. Lorsqu'ils sont utilisés ensemble, le point de rupture de cache automatique utilise l'un des 4 emplacements de points de rupture disponibles.

Cela vous permet de combiner les deux approches. Par exemple, utilisez un point de rupture 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 de rupture explicites.



Cas limites

• Si le dernier bloc a déjà un cache_control explicite avec le même TTL, la mise en cache automatique est sans effet.
• Si le dernier bloc a un cache_control explicite avec un TTL différent, l'API renvoie une erreur 400.
• Si 4 points de rupture 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 de rupture de cache automatique, le système remonte silencieusement en arrière pour trouver le bloc éligible le plus proche. Si aucun n'est trouvé, la mise en cache est ignorée.



Points de rupture de cache explicites

Pour plus de contrôle 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.



Comment fonctionne la vérification automatique des préfixes

Vous pouvez utiliser un seul point de rupture 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 comment cela fonctionne vous aide à optimiser votre stratégie de mise en cache.

Trois principes fondamentaux :

1. Les écritures de cache se produisent uniquement à votre point de rupture. 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 ce qui précède le point de rupture, inclus, modifier n'importe quel bloc au niveau du point de rupture ou avant produit un hachage différent lors de la requête suivante.

2. Les lectures de cache recherchent en arrière les entrées que les requêtes antérieures ont écrites. À chaque requête, le système calcule le hachage du préfixe à votre point de rupture et vérifie s'il existe une entrée de cache correspondante. Si aucune n'existe, il remonte en arrière 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 de rupture, en comptant le point de rupture 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 prochain point de rupture explicite, 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 de rupture 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 de rupture 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. 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 de rupture 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 est une position en dehors de la fenêtre, il n'y a donc pas de succès de cache. L'ajout d'un deuxième point de rupture 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 de rupture sur du 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 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. Aucun succès de cache. Vous payez une nouvelle écriture de cache à chaque requête et n'obtenez jamais de lecture.

La recherche arrière ne trouve pas le contenu stable derrière votre point de rupture pour le mettre en cache. Elle trouve les entrées que les requêtes antérieures ont déjà écrites, et les écritures ne se produisent qu'aux points de rupture. 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 de rupture 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 de rupture explicite sur le bloc 5.

Point clé : Placez cache_control sur le dernier bloc dont le préfixe est identique entre les requêtes qui doivent 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 propre à chaque requête, le message entrant), placez le point de rupture à la fin du préfixe statique, pas sur le bloc variable.



Quand utiliser plusieurs points de rupture

Vous pouvez définir jusqu'à 4 points de rupture 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 un succès de cache lorsqu'une conversation croissante pousse votre point de rupture à 20 blocs ou plus au-delà de la dernière écriture de cache



Comprendre les coûts des points de rupture de cache

Les points de rupture de cache eux-mêmes n'ajoutent aucun coût. Vous n'êtes facturé que 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 le contenu mis en cache est utilisé (10 % du prix de base des tokens d'entrée)
• Les tokens d'entrée réguliers : Pour tout contenu non mis en cache

L'ajout de points de rupture 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 de rupture 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 de :

• 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 (déprécié), 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 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'a pas atteint 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 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 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, 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 : Les définitions d'outils dans le tableau tools
• Messages système : Les blocs de contenu dans le tableau system
• Messages texte : Les blocs de contenu dans le tableau messages.content, pour les tours utilisateur et assistant
• Images et documents : Les blocs de contenu dans le tableau messages.content, dans les tours utilisateur
• Utilisation d'outils et résultats d'outils : Les 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 assistant précédents. Lorsqu'ils sont mis en cache de cette manière, ils comptent BIEN comme 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 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 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 du contenu mis en cache peuvent invalider une partie ou la totalité 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 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 le cache ni utilisés pour en créer un (c'est-à-dire les tokens après le dernier point de rupture de cache).

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens



Mise en cache avec des 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 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é, 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 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 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. Depuis le 5 février 2026, 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 continuent d'utiliser uniquement l'isolation au niveau de l'organisation.

• Correspondance exacte : Les succès de cache nécessitent des segments de prompt 100 % identiques, y compris tout le texte et les images jusqu'au bloc marqué avec le contrôle de cache, 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 de rupture.
• Utilisez des points de rupture 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 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 de rupture 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 de rupture 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, le message entrant), il s'agit de la fin du préfixe, pas 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 le coût et la latence pour les conversations prolongées, en particulier celles avec 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 contenu 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.
• Dialoguez 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 laissant les utilisateurs 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 entre les appels. Pour les points de rupture explicites, vérifiez que les marqueurs cache_control sont 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
• Validez que vous mettez en cache au moins le nombre minimum de tokens pour votre modèle et votre plateforme (consultez Limitations du cache)
• Confirmez que votre point de rupture se trouve sur un bloc qui reste identique d'une requête à l'autre. Les écritures de cache ne se produisent qu'au point de rupture, et si ce bloc change (horodatages, contexte propre à chaque requête, le message entrant), le hachage du préfixe ne correspond jamais. La recherche arrière ne trouve pas le contenu stable derrière le point de rupture ; elle ne trouve que les entrées que des requêtes antérieures ont écrites à leurs propres points de rupture
• 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 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 ce qui 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 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 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 le plus utile dans les scénarios suivants :

• Lorsque vous avez des prompts qui sont probablement 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 lors du stockage d'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éduits 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 avec un TTL plus long doivent apparaître avant les TTL plus courts (c'est-à-dire qu'une entrée de cache d'une 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 au succès de cache le plus élevé (ou 0 s'il n'y a aucun 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 de cache pour A.
2. Les tokens d'écriture de cache d'une 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 succès 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 à un échec de cache lors de la première interaction utilisateur, réduisant le « time-to-first-token » (délai jusqu'au premier token), ou TTFT, pour les applications sensibles à la latence.



Comment ça fonctionne

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

Placez le point de rupture cache_control sur le dernier bloc qui est 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 de substitution. Sinon, l'entrée de cache est indexée sur le message de substitution et la requête de suivi ne l'atteindra pas. Utilisez également la même configuration de réflexion et le même 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 signifie utiliser un point de rupture de cache explicite plutôt que la mise en cache automatique, puisque la mise en cache automatique place le point de rupture sur le dernier bloc, qui est ici le message de substitution. Le message utilisateur de substitution peut être n'importe quelle chaîne avec un contenu non vide (les exemples ici utilisent "warmup") ; son contenu est lu dans le modèle mais jamais traité en réponse.

client = anthropic.Anthropic()

# Déclenchez 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"
  }
}



Modèle d'utilisation typique

Envoyez une requête de préchauffage au démarrage de votre application (ou à intervalle régulier), puis envoyez les vraies requêtes utilisateur 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échauffer le cache avant l'arrivée du 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 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'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": "tool", ...} ou {"type": "any"}

max_tokens: 0 est également rejeté dans une requête Message Batches. Le préchauffage cible le temps jusqu'au 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 de la solution de 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 modèles 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 au repos. Les entrées mises en cache ont une durée de vie minimale de 5 minutes (standard) ou 1 heure (étendue), après quoi elles sont rapidement, mais pas immédiatement, supprimées. 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é au ZDR pour toutes les fonctionnalités, consultez API et conservation des données.



FAQ