Mise en cache des prompts

La mise en cache des prompts est une fonctionnalité puissante qui optimise votre utilisation de l’API en permettant de reprendre à partir de préfixes spécifiques dans vos prompts. Cette approche réduit considérablement le temps de traitement et les coûts pour les tâches répétitives ou les prompts avec des éléments cohérents. Voici un exemple de comment implémenter la mise en cache des prompts avec l’API Messages en utilisant un bloc cache_control :

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "Vous êtes un assistant IA chargé d'analyser des œuvres littéraires. Votre objectif est de fournir des commentaires perspicaces sur les thèmes, les personnages et le style d'écriture.\n"
      },
      {
        "type": "text",
        "text": "<tout le contenu d'Orgueil et Préjugés>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analysez les thèmes principaux dans Orgueil et Préjugés."
      }
    ]
  }'

# Appelez le modèle à nouveau avec les mêmes entrées jusqu'au point de contrôle du cache
curl https://api.anthropic.com/v1/messages # reste de l'entrée

JSON

{"cache_creation_input_tokens":188086,"cache_read_input_tokens":0,"input_tokens":21,"output_tokens":393}
{"cache_creation_input_tokens":0,"cache_read_input_tokens":188086,"input_tokens":21,"output_tokens":393}

Dans cet exemple, tout le texte d‘“Orgueil et Préjugés” est mis en cache en utilisant le paramètre cache_control. Cela permet la réutilisation de ce texte volumineux à travers plusieurs appels API sans le retraiter à chaque fois. Changer seulement le message utilisateur vous permet de poser diverses questions sur le livre tout en utilisant le contenu mis en cache, conduisant à des réponses plus rapides et une efficacité améliorée.

Comment fonctionne la mise en cache des prompts

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

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.
S’il est trouvé, il utilise la version mise en cache, réduisant le temps de traitement et les coûts.
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 avec de nombreux exemples
De grandes quantités de contexte ou d’informations de base
Les tâches répétitives avec des instructions cohérentes
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é.

Si vous trouvez que 5 minutes est trop court, Anthropic offre également une durée de cache de 1 heure.Pour plus d’informations, voir Durée de cache de 1 heure.

La mise en cache des prompts met en cache le préfixe completLa mise en cache des prompts fait référence au prompt entier - tools, system, et messages (dans cet ordre) jusqu’au bloc désigné avec cache_control inclus.

Tarification

La mise en cache des prompts introduit une nouvelle structure de tarification. Le tableau ci-dessous montre le prix par million de tokens pour chaque modèle pris en charge :

Model	Base Input Tokens	5m Cache Writes	1h Cache Writes	Cache Hits & Refreshes	Output Tokens
Claude Opus 4.1	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Opus 4	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Sonnet 4	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.7	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.5 (deprecated)	$3 / MTok	$3.75 / MTok	$6 / MTok	$0.30 / MTok	$15 / MTok
Claude Haiku 3.5	$0.80 / MTok	$1 / MTok	$1.6 / MTok	$0.08 / MTok	$4 / MTok
Claude Opus 3 (deprecated)	$15 / MTok	$18.75 / MTok	$30 / MTok	$1.50 / MTok	$75 / MTok
Claude Haiku 3	$0.25 / MTok	$0.30 / MTok	$0.50 / MTok	$0.03 / MTok	$1.25 / MTok

Le tableau ci-dessus reflète les multiplicateurs de tarification suivants pour la mise en cache des prompts :

Les tokens d’écriture de cache de 5 minutes coûtent 1,25 fois le prix des tokens d’entrée de base
Les tokens d’écriture de cache de 1 heure coûtent 2 fois le prix des tokens d’entrée de base
Les tokens de lecture de cache coûtent 0,1 fois le prix des tokens d’entrée de base

Comment implémenter la mise en cache des prompts

Modèles pris en charge

La mise en cache des prompts est actuellement prise en charge sur :

Claude Opus 4.1
Claude Opus 4
Claude Sonnet 4
Claude Sonnet 3.7
Claude Sonnet 3.5 (déprécié)
Claude Haiku 3.5
Claude Haiku 3
Claude Opus 3 (déprécié)

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 en utilisant le 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 juste un point d’arrêt de cache à la fin de votre contenu statique, et le système trouvera automatiquement le préfixe correspondant le plus long. Voici comment cela fonctionne :

Lorsque vous ajoutez un point d’arrêt cache_control, le système vérifie automatiquement les correspondances de cache à toutes les limites de blocs de contenu précédentes (jusqu’à environ 20 blocs avant votre point d’arrêt explicite)
Si l’une de ces positions précédentes correspond au contenu mis en cache de requêtes antérieures, le système utilise le préfixe correspondant le plus long
Cela signifie que vous n’avez pas besoin de plusieurs points d’arrêt juste pour activer la mise en cache - un à la fin est suffisant

Quand utiliser plusieurs points d’arrêt

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

Mettre en cache différentes sections qui changent à différentes fréquences (par exemple, les outils changent rarement, mais le contexte se met à jour quotidiennement)
Avoir plus de contrôle sur exactement ce qui est mis en cache
Assurer la mise en cache pour le contenu plus de 20 blocs avant votre point d’arrêt final

Limitation importante : La vérification automatique des préfixes ne regarde en arrière qu’environ 20 blocs de contenu à partir de chaque point d’arrêt explicite. Si votre prompt a plus de 20 blocs de contenu avant votre point d’arrêt de cache, le contenu antérieur à cela ne sera pas vérifié pour les correspondances de cache à moins que vous n’ajoutiez des points d’arrêt supplémentaires.

Limitations du cache

La longueur minimale de prompt pouvant être mise en cache est :

1024 tokens pour Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (déprécié) et Claude Opus 3 (déprécié)
2048 tokens pour Claude Haiku 3.5 et Claude Haiku 3

Les prompts plus courts ne peuvent pas être mis en cache, même s’ils sont marqués avec cache_control. Toute requête pour mettre en cache moins que ce nombre de tokens sera traitée sans mise en cache. Pour voir si un prompt a été mis en cache, voir les champs d’utilisation de la réponse. 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.

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 :

Écritures de cache : Lorsque du nouveau contenu est écrit dans le cache (25% de plus que les tokens d’entrée de base pour TTL de 5 minutes)
Lectures de cache : Lorsque le contenu mis en cache est utilisé (10% du prix des tokens d’entrée de base)
Tokens d’entrée réguliers : 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 basé sur quel contenu est réellement mis en cache et lu. Les points d’arrêt vous donnent simplement le contrôle sur quelles sections peuvent être mises en cache indépendamment.

Ce qui peut être mis en cache

La plupart des blocs dans la requête peuvent être désignés pour la mise en cache avec cache_control. 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 marqué avec cache_control pour activer la mise en cache pour cette portion de la requête.

Ce qui ne peut pas être mis en cache

Bien que la plupart des blocs de requête puissent être mis en cache, il y a 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’autre contenu lorsqu’ils apparaissent dans les tours d’assistant précédents. Lorsqu’ils sont mis en cache de cette façon, ils COMPTENT comme 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. Au lieu de cela, mettez 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 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 changements à 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 changements. ✘ indique que le cache est invalidé, tandis que ✓ indique que le cache reste valide.

Ce qui change	Cache des outils	Cache système	Cache des messages	Impact
Définitions d’outils	✘	✘	✘	Modifier les définitions d’outils (noms, descriptions, paramètres) invalide tout le cache
Basculement de recherche web	✓	✘	✘	Activer/désactiver la recherche web modifie le prompt système
Basculement des citations	✓	✘	✘	Activer/désactiver les citations modifie le prompt système
Choix d’outil	✓	✓	✘	Les changements au paramètre `tool_choice` n’affectent que les blocs de messages
Images	✓	✓	✘	Ajouter/supprimer des images n’importe où dans le prompt affecte les blocs de messages
Paramètres de réflexion	✓	✓	✘	Les changements aux paramètres de réflexion étendue (activer/désactiver, budget) affectent les blocs de messages
Résultats non-outils passés aux requêtes de réflexion étendue	✓	✓	✘	Lorsque des résultats non-outils sont passés dans les requêtes pendant que la réflexion étendue est activée, tous les blocs de réflexion précédemment mis en cache sont supprimés du contexte, et tous les messages dans le contexte qui suivent ces blocs de réflexion sont supprimés du cache. Pour plus de détails, voir Mise en cache avec les blocs de réflexion.

Suivi des performances du cache

Surveillez les performances du cache en utilisant ces champs de réponse API, dans usage dans la réponse (ou événement message_start si 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 du cache pour cette requête.
input_tokens : Nombre de tokens d’entrée qui n’ont pas été lus depuis ou utilisés pour créer un cache.

Meilleures pratiques pour une mise en cache efficace

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

Mettez en cache le contenu stable et réutilisable comme les instructions système, les informations de base, 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 stratégiquement pour séparer différentes sections de préfixes pouvant être mises en cache.
Analysez régulièrement les taux de correspondance de cache et ajustez votre stratégie selon les besoins.

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 étendues, en particulier celles avec de longues instructions ou des documents téléchargés.
Assistants de codage : Améliorez l’autocomplétion et les Q&R de base de code en gardant 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 complet de forme longue incluant des images dans votre prompt sans augmenter la latence de réponse.
Ensembles d’instructions détaillées : 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 exemple ou deux dans le prompt, mais avec la mise en cache des prompts, vous pouvez obtenir de meilleures performances en incluant 20+ exemples divers de réponses de haute qualité.
Utilisation d’outils agentiques : Améliorez les performances pour les scénarios impliquant plusieurs appels d’outils et des changements de code itératifs, où chaque étape nécessite typiquement un nouvel appel API.
Parler aux livres, papiers, documentation, transcriptions de podcasts, et autre contenu de forme longue : Donnez vie à toute base de connaissances en intégrant le(s) document(s) entier(s) dans le prompt, et laissez les utilisateurs lui poser des questions.

Dépannage des problèmes courants

Si vous rencontrez un comportement inattendu :

Assurez-vous que les sections mises en cache sont identiques et marquées avec cache_control aux mêmes emplacements à travers les appels
Vérifiez que les appels sont faits dans la durée de vie du cache (5 minutes par défaut)
Vérifiez que tool_choice et l’utilisation d’images restent cohérents entre les appels
Validez que vous mettez en cache au moins le nombre minimum de tokens
Le système vérifie automatiquement les correspondances de cache aux limites de blocs de contenu précédentes (jusqu’à ~20 blocs avant votre point d’arrêt). Pour les prompts avec plus de 20 blocs de contenu, vous pourriez avoir besoin de paramètres cache_control supplémentaires plus tôt dans le prompt pour assurer que tout le contenu peut être mis en cache

Les changements à tool_choice ou la présence/absence d’images n’importe où dans le prompt invalideront le cache, nécessitant qu’une nouvelle entrée de cache soit créée. Pour plus de détails sur l’invalidation du cache, voir Ce qui invalide le cache.

Mise en cache avec les blocs de réflexion

Lors de l’utilisation de la réflexion étendue avec la mise en cache des prompts, les blocs de réflexion ont un comportement spécial : Mise en cache automatique avec d’autre contenu : 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 faites des appels API suivants avec des résultats d’outils. Cela arrive couramment pendant l’utilisation d’outils lorsque vous renvoyez les blocs de réflexion pour continuer 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. Modèles d’invalidation du cache :

Le cache reste valide lorsque seuls les résultats d’outils sont fournis comme messages utilisateur
Le cache est invalidé lorsque du contenu utilisateur non-résultat-d’outil est ajouté, causant la suppression de tous les blocs de réflexion précédents
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, voir Ce qui invalide le cache. Exemple avec utilisation d’outils :

Requête 1 : Utilisateur : "Quel est le temps à Paris ?"
Réponse : [bloc_de_réflexion_1] + [bloc d'utilisation d'outil 1]

Requête 2 : 
Utilisateur : ["Quel est le temps à Paris ?"], 
Assistant : [bloc_de_réflexion_1] + [bloc d'utilisation d'outil 1], 
Utilisateur : [résultat_outil_1, cache=True]
Réponse : [bloc_de_réflexion_2] + [bloc de texte 2]
# La requête 2 met en cache son contenu de requête (pas la réponse)
# Le cache inclut : message utilisateur, bloc_de_réflexion_1, bloc d'utilisation d'outil 1, et résultat_outil_1

Requête 3 :
Utilisateur : ["Quel est le temps à Paris ?"], 
Assistant : [bloc_de_réflexion_1] + [bloc d'utilisation d'outil 1], 
Utilisateur : [résultat_outil_1, cache=True], 
Assistant : [bloc_de_réflexion_2] + [bloc de texte 2], 
Utilisateur : [Réponse texte, cache=True]
# Le bloc utilisateur non-résultat-d'outil cause l'ignorance de tous les blocs de réflexion
# Cette requête est traitée comme si les blocs de réflexion n'étaient jamais présents

Lorsqu’un bloc utilisateur non-résultat-d’outil est inclus, il désigne une nouvelle boucle d’assistant et tous les blocs de réflexion précédents sont supprimés du contexte. Pour des informations plus détaillées, voir la documentation de réflexion étendue.

Stockage et partage du cache

Isolation d’organisation : Les caches sont isolés entre les organisations. Différentes organisations ne partagent jamais les caches, même si elles utilisent des prompts identiques.
Correspondance exacte : Les correspondances de cache nécessitent des segments de prompt 100% identiques, incluant tout le texte et les images jusqu’au bloc marqué avec 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 sera identique à ce que vous obtiendriez si la mise en cache des prompts n’était pas utilisée.

Durée de cache de 1 heure

Si vous trouvez que 5 minutes est trop court, Anthropic offre également une durée de cache de 1 heure. Pour utiliser le cache étendu, incluez ttl dans la définition cache_control comme ceci :

"cache_control": {
    "type": "ephemeral",
    "ttl": "5m" | "1h"
}

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

{
    "usage": {
        "input_tokens": ...,
        "cache_read_input_tokens": ...,
        "cache_creation_input_tokens": ...,
        "output_tokens": ...,
        
        "cache_creation": {
            "ephemeral_5m_input_tokens": 456,
            "ephemeral_1h_input_tokens": 100,
        }
    }
}

Notez que le champ actuel cache_creation_input_tokens égale la somme des valeurs dans l’objet cache_creation.

Quand utiliser le cache de 1 heure

Si vous avez des prompts qui sont utilisés à une cadence régulière (c’est-à-dire, des prompts système qui sont utilisés 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 mieux utilisé dans les scénarios suivants :

Lorsque vous avez des prompts qui sont probablement utilisés moins fréquemment que 5 minutes, mais plus fréquemment que toutes les heures. Par exemple, lorsqu’un agent agentique secondaire prendra plus de 5 minutes, ou lors du stockage d’une longue conversation de chat avec un utilisateur et vous vous attendez généralement à ce que cet utilisateur ne réponde pas dans les 5 minutes suivantes.
Lorsque la latence est importante et vos prompts de suivi peuvent être envoyés au-delà de 5 minutes.
Lorsque vous voulez améliorer votre utilisation de limite de taux, car les correspondances de cache ne sont pas déduites de votre limite de taux.

Le cache de 5 minutes et de 1 heure se comportent de la même manière en ce qui concerne la latence. Vous verrez généralement un temps-au-premier-token amélioré pour les documents longs.

Mélanger différents TTL

Vous pouvez utiliser à la fois les 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, 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, nous déterminons trois emplacements de facturation dans votre prompt :

Position A : Le nombre de tokens à la correspondance de cache la plus élevée (ou 0 s’il n’y a pas de correspondances).
Position B : Le nombre de tokens au bloc cache_control de 1 heure le plus élevé après A (ou égale A si aucun n’existe).
Position C : Le nombre de tokens au dernier bloc cache_control.

Si B et/ou C sont plus grands que A, ils seront nécessairement des échecs de cache, car A est la correspondance de cache la plus élevée.

Vous serez facturé pour :

Tokens de lecture de cache pour A.
Tokens d’écriture de cache de 1 heure pour (B - A).
Tokens d’écriture de cache de 5 minutes pour (C - B).

Voici 3 exemples. Ceci représente les tokens d’entrée de 3 requêtes, chacune ayant différentes correspondances et échecs de cache. Chacune a une tarification calculée différente, montrée dans les boîtes colorées, en conséquence.

Exemples de mise en cache des prompts

Pour vous aider à commencer avec la mise en cache des prompts, nous avons préparé un livre de recettes de mise en cache des prompts avec des exemples détaillés et les meilleures pratiques. Ci-dessous, nous avons inclus plusieurs extraits de code qui présentent divers modèles de mise en cache des prompts. Ces exemples démontrent comment implémenter la mise en cache dans différents scénarios, vous aidant à comprendre les applications pratiques de cette fonctionnalité :

Exemple de mise en cache de contexte volumineux

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "Vous êtes un assistant IA chargé d'analyser des documents juridiques."
        },
        {
            "type": "text",
            "text": "Voici le texte complet d'un accord juridique complexe : [Insérer le texte complet d'un accord juridique de 50 pages ici]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Quels sont les termes et conditions clés dans cet accord ?"
        }
    ]
}'

Cet exemple démontre l’utilisation de base de la mise en cache des prompts, mettant en cache le texte complet de l’accord juridique comme préfixe tout en gardant l’instruction utilisateur non mise en cache.Pour la première requête :

input_tokens : Nombre de tokens dans le message utilisateur seulement
cache_creation_input_tokens : Nombre de tokens dans tout le message système, incluant le document juridique
cache_read_input_tokens : 0 (pas de correspondance de cache sur la première requête)

Pour les requêtes suivantes dans la durée de vie du cache :

input_tokens : Nombre de tokens dans le message utilisateur seulement
cache_creation_input_tokens : 0 (pas de nouvelle création de cache)
cache_read_input_tokens : Nombre de tokens dans tout le message système mis en cache

Mise en cache des définitions d'outils

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Obtenir la météo actuelle dans un lieu donné",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "La ville et l'état, par exemple San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "L'unité de température, soit celsius soit fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # beaucoup plus d'outils
        {
            "name": "get_time",
            "description": "Obtenir l'heure actuelle dans un fuseau horaire donné",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "Le nom de fuseau horaire IANA, par exemple America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Quelle est la météo et l'heure à New York ?"
        }
    ]
}'

Dans cet exemple, nous démontrons la mise en cache des définitions d’outils.Le paramètre cache_control est placé sur l’outil final (get_time) pour désigner tous les outils comme faisant partie du préfixe statique.Cela signifie que toutes les définitions d’outils, incluant get_weather et tout autre outil défini avant get_time, seront mises en cache comme un seul préfixe.Cette approche est utile lorsque vous avez un ensemble cohérent d’outils que vous voulez réutiliser à travers plusieurs requêtes sans les retraiter à chaque fois.Pour la première requête :

input_tokens : Nombre de tokens dans le message utilisateur
cache_creation_input_tokens : Nombre de tokens dans toutes les définitions d’outils et le prompt système
cache_read_input_tokens : 0 (pas de correspondance de cache sur la première requête)

Pour les requêtes suivantes dans la durée de vie du cache :

input_tokens : Nombre de tokens dans le message utilisateur
cache_creation_input_tokens : 0 (pas de nouvelle création de cache)
cache_read_input_tokens : Nombre de tokens dans toutes les définitions d’outils mises en cache et le prompt système

Continuer une conversation multi-tours

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long prompt système",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Bonjour, pouvez-vous me parler davantage du système solaire ?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certainement ! Le système solaire est la collection de corps célestes qui orbitent autour de notre Soleil. Il se compose de huit planètes, de nombreuses lunes, astéroïdes, comètes et autres objets. Les planètes, dans l'ordre du plus proche au plus éloigné du Soleil, sont : Mercure, Vénus, Terre, Mars, Jupiter, Saturne, Uranus et Neptune. Chaque planète a ses propres caractéristiques et fonctionnalités uniques. Y a-t-il un aspect spécifique du système solaire sur lequel vous aimeriez en savoir plus ?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Bon à savoir."
                },
                {
                    "type": "text",
                    "text": "Parlez-moi davantage de Mars.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

Dans cet exemple, nous démontrons comment utiliser la mise en cache des prompts dans une conversation multi-tours.Pendant chaque tour, nous marquons le bloc final du message final avec cache_control pour que la conversation puisse être mise en cache de manière incrémentale. Le système recherchera automatiquement et utilisera le préfixe mis en cache le plus long précédemment pour les messages de suivi. C’est-à-dire, les blocs qui étaient précédemment marqués avec un bloc cache_control ne sont plus marqués avec ceci plus tard, mais ils seront toujours considérés comme une correspondance de cache (et aussi un rafraîchissement de cache !) s’ils sont touchés dans les 5 minutes.De plus, notez que le paramètre cache_control est placé sur le message système. Ceci est pour s’assurer que si cela est évincé du cache (après ne pas avoir été utilisé pendant plus de 5 minutes), il sera rajouté au cache lors de la prochaine requête.Cette approche est utile pour maintenir le contexte dans les conversations en cours sans traiter de manière répétée les mêmes informations.Lorsque ceci est configuré correctement, vous devriez voir ce qui suit dans la réponse d’utilisation de chaque requête :

input_tokens : Nombre de tokens dans le nouveau message utilisateur (sera minimal)
cache_creation_input_tokens : Nombre de tokens dans les nouveaux tours assistant et utilisateur
cache_read_input_tokens : Nombre de tokens dans la conversation jusqu’au tour précédent

Tout assembler : Multiples points d'arrêt de cache

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Rechercher dans la base de connaissances",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Requête de recherche"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Récupérer un document spécifique par ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "ID du document"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "Vous êtes un assistant de recherche utile avec accès à une base de connaissances de documents.\n\n# Instructions\n- Toujours rechercher des documents pertinents avant de répondre\n- Fournir des citations pour vos sources\n- Être objectif et précis dans vos réponses\n- Si plusieurs documents contiennent des informations pertinentes, les synthétiser\n- Reconnaître quand l'information n'est pas disponible dans la base de connaissances",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Contexte de la base de connaissances\n\nVoici les documents pertinents pour cette conversation :\n\n## Document 1 : Aperçu du système solaire\nLe système solaire se compose du Soleil et de tous les objets qui l'orbitent...\n\n## Document 2 : Caractéristiques planétaires\nChaque planète a des caractéristiques uniques. Mercure est la plus petite planète...\n\n## Document 3 : Exploration de Mars\nMars a été une cible d'exploration pendant des décennies...\n\n[Documents supplémentaires...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Pouvez-vous rechercher des informations sur les rovers martiens ?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "rovers martiens"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Trouvé 3 documents pertinents : Document 3 (Exploration de Mars), Document 7 (Technologie des rovers), Document 9 (Historique des missions)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "J'ai trouvé 3 documents pertinents sur les rovers martiens. Laissez-moi obtenir plus de détails du document Exploration de Mars."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Oui, s'il vous plaît parlez-moi spécifiquement du rover Perseverance.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

Cet exemple complet démontre comment utiliser les 4 points d’arrêt de cache disponibles pour optimiser différentes parties de votre prompt :

Cache des outils (point d’arrêt de cache 1) : Le paramètre cache_control sur la dernière définition d’outil met en cache toutes les définitions d’outils.
Cache des instructions réutilisables (point d’arrêt de cache 2) : Les instructions statiques dans le prompt système sont mises en cache séparément. Ces instructions changent rarement entre les requêtes.
Cache de contexte RAG (point d’arrêt de cache 3) : Les documents de la base de connaissances sont mis en cache indépendamment, vous permettant de mettre à jour les documents RAG sans invalider le cache des outils ou des instructions.
Cache de l’historique de conversation (point d’arrêt de cache 4) : La réponse de l’assistant est marquée avec cache_control pour permettre la mise en cache incrémentale de la conversation au fur et à mesure qu’elle progresse.

Cette approche fournit une flexibilité maximale :

Si vous ne mettez à jour que le message utilisateur final, les quatre segments de cache sont réutilisés
Si vous mettez à jour les documents RAG mais gardez les mêmes outils et instructions, les deux premiers segments de cache sont réutilisés
Si vous changez la conversation mais gardez les mêmes outils, instructions et documents, les trois premiers segments sont réutilisés
Chaque point d’arrêt de cache peut être invalidé indépendamment basé sur ce qui change dans votre application

Pour la première requête :

input_tokens : Tokens dans le message utilisateur final
cache_creation_input_tokens : Tokens dans tous les segments mis en cache (outils + instructions + documents RAG + historique de conversation)
cache_read_input_tokens : 0 (pas de correspondances de cache)

Pour les requêtes suivantes avec seulement un nouveau message utilisateur :

input_tokens : Tokens dans le nouveau message utilisateur seulement
cache_creation_input_tokens : Tous nouveaux tokens ajoutés à l’historique de conversation
cache_read_input_tokens : Tous les tokens précédemment mis en cache (outils + instructions + documents RAG + conversation précédente)

Ce modèle est particulièrement puissant pour :

Les applications RAG avec de grands contextes de documents
Les systèmes d’agents qui utilisent plusieurs outils
Les conversations de longue durée qui ont besoin de maintenir le contexte
Les applications qui ont besoin d’optimiser différentes parties du prompt indépendamment

FAQ

Ai-je besoin de plusieurs points d'arrêt de cache ou un seul à la fin est-il suffisant ?

Les points d'arrêt de cache ajoutent-ils des coûts supplémentaires ?

Quelle est la durée de vie du cache ?

Combien de points d'arrêt de cache puis-je utiliser ?

La mise en cache des prompts est-elle disponible pour tous les modèles ?

Comment la mise en cache des prompts fonctionne-t-elle avec la réflexion étendue ?

Comment activer la mise en cache des prompts ?

Puis-je utiliser la mise en cache des prompts avec d'autres fonctionnalités de l'API ?

Comment la mise en cache des prompts affecte-t-elle la tarification ?

Puis-je effacer manuellement le cache ?

Comment puis-je suivre l'efficacité de ma stratégie de mise en cache ?

Qu'est-ce qui peut casser le cache ?

Comment la mise en cache des prompts gère-t-elle la confidentialité et la séparation des données ?

Puis-je utiliser la mise en cache des prompts avec l'API Batches ?

Pourquoi est-ce que je vois l'erreur `AttributeError: 'Beta' object has no attribute 'prompt_caching'` en Python ?

Cette erreur apparaît typiquement lorsque vous avez mis à niveau votre SDK ou vous utilisez des exemples de code obsolètes. La mise en cache des prompts est maintenant généralement disponible, donc vous n’avez plus besoin du préfixe beta. Au lieu de :

python client.beta.prompt_caching.messages.create(...)

Utilisez simplement :

python client.messages.create(...)

Pourquoi est-ce que je vois 'TypeError: Cannot read properties of undefined (reading 'messages')' ?

TypeScript

client.beta.promptCaching.messages.create(...)

Utilisez simplement :

client.messages.create(...)

Premiers pas

Modèles et tarification

Découvrir Claude

Capacités

Outils

Protocole de Contexte de Modèle (MCP)

Cas d'usage

Ingénierie de prompts

Tester et évaluer

Renforcer les garde-fous

Centre juridique

Mise en cache des prompts

Comment fonctionne la mise en cache des prompts

Tarification

Comment implémenter la mise en cache des prompts

Modèles pris en charge

Structurer votre prompt

Comment fonctionne la vérification automatique des préfixes

Quand utiliser plusieurs points d’arrêt

Limitations du cache

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

Ce qui peut être mis en cache

Ce qui ne peut pas être mis en cache

Ce qui invalide le cache

Suivi des performances du cache

Meilleures pratiques pour une mise en cache efficace

Optimisation pour différents cas d’usage

Dépannage des problèmes courants

Mise en cache avec les blocs de réflexion

Stockage et partage du cache

Durée de cache de 1 heure

Quand utiliser le cache de 1 heure

Mélanger différents TTL

Exemples de mise en cache des prompts

FAQ

Premiers pas

Modèles et tarification

Découvrir Claude

Capacités

Outils

Protocole de Contexte de Modèle (MCP)

Cas d'usage

Ingénierie de prompts

Tester et évaluer

Renforcer les garde-fous

Centre juridique

​Comment fonctionne la mise en cache des prompts

​Tarification

​Comment implémenter la mise en cache des prompts

​Modèles pris en charge

​Structurer votre prompt

​Comment fonctionne la vérification automatique des préfixes

​Quand utiliser plusieurs points d’arrêt

​Limitations du cache

​Comprendre les coûts des points d’arrêt de cache

​Ce qui peut être mis en cache

​Ce qui ne peut pas être mis en cache

​Ce qui invalide le cache

​Suivi des performances du cache

​Meilleures pratiques pour une mise en cache efficace

​Optimisation pour différents cas d’usage

​Dépannage des problèmes courants

​Mise en cache avec les blocs de réflexion

​Stockage et partage du cache

​Durée de cache de 1 heure

​Quand utiliser le cache de 1 heure

​Mélanger différents TTL

​Exemples de mise en cache des prompts

​FAQ

Comment fonctionne la mise en cache des prompts

Tarification

Comment implémenter la mise en cache des prompts

Modèles pris en charge

Structurer votre prompt

Comment fonctionne la vérification automatique des préfixes

Quand utiliser plusieurs points d’arrêt

Limitations du cache

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

Ce qui peut être mis en cache

Ce qui ne peut pas être mis en cache

Ce qui invalide le cache

Suivi des performances du cache

Meilleures pratiques pour une mise en cache efficace

Optimisation pour différents cas d’usage

Dépannage des problèmes courants

Mise en cache avec les blocs de réflexion

Stockage et partage du cache

Durée de cache de 1 heure

Quand utiliser le cache de 1 heure

Mélanger différents TTL

Exemples de mise en cache des prompts

FAQ