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 :

Shell

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 :

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 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 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 complet

La 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 :

1. Position A : Le nombre de tokens à la correspondance de cache la plus élevée (ou 0 s’il n’y a pas de correspondances).
2. 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).
3. 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 :

1. Tokens de lecture de cache pour A.
2. Tokens d’écriture de cache de 1 heure pour (B - A).
3. 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

Shell

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

Shell

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

Shell

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

Shell

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 :

1. 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.

2. 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.

3. 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.

4. 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 ?

Dans la plupart des cas, un seul point d’arrêt de cache à la fin de votre contenu statique est suffisant. Le système vérifie automatiquement les correspondances de cache à toutes les limites de blocs de contenu précédentes (jusqu’à 20 blocs avant votre point d’arrêt) et utilise le préfixe correspondant le plus long.

Vous n’avez besoin de plusieurs points d’arrêt que si :

• Vous avez plus de 20 blocs de contenu avant votre point de cache désiré
• Vous voulez mettre en cache des sections qui se mettent à jour à différentes fréquences indépendamment
• Vous avez besoin d’un contrôle explicite sur ce qui est mis en cache pour l’optimisation des coûts

Exemple : Si vous avez des instructions système (changent rarement) et un contexte RAG (change quotidiennement), vous pourriez utiliser deux points d’arrêt pour les mettre en cache séparément.

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

Non, les points d’arrêt de cache eux-mêmes sont gratuits. Vous ne payez que pour :

• Écrire du contenu dans le cache (25% de plus que les tokens d’entrée de base pour TTL de 5 minutes)
• Lire depuis le cache (10% du prix des tokens d’entrée de base)
• Tokens d’entrée réguliers pour le contenu non mis en cache

Le nombre de points d’arrêt n’affecte pas la tarification - seule la quantité de contenu mis en cache et lu importe.

Quelle est la durée de vie du cache ?

La durée de vie minimale par défaut du cache (TTL) est de 5 minutes. Cette durée de vie est actualisée chaque fois que le contenu mis en cache est utilisé.

Si vous trouvez que 5 minutes est trop court, Anthropic offre également un TTL de cache de 1 heure.

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

Vous pouvez définir jusqu’à 4 points d’arrêt de cache (en utilisant les paramètres cache_control) dans votre prompt.

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

Non, la mise en cache des prompts n’est actuellement disponible que pour 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, et Claude Opus 3 (déprécié).

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

Les prompts système et outils mis en cache seront réutilisés lorsque les paramètres de réflexion changent. Cependant, les changements de réflexion (activer/désactiver ou changements de budget) invalideront les préfixes de prompt précédemment mis en cache avec le contenu des messages.

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

Pour plus sur la réflexion étendue, incluant son interaction avec l’utilisation d’outils et la mise en cache des prompts, voir la documentation de réflexion étendue.

Comment activer la mise en cache des prompts ?

Pour activer la mise en cache des prompts, incluez au moins un point d’arrêt cache_control dans votre requête API.

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

Oui, la mise en cache des prompts peut être utilisée avec d’autres fonctionnalités de l’API comme l’utilisation d’outils et les capacités de vision. Cependant, changer s’il y a des images dans un prompt ou modifier les paramètres d’utilisation d’outils cassera le cache.

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

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

La mise en cache des prompts introduit une nouvelle structure de tarification où les écritures de cache coûtent 25% de plus que les tokens d’entrée de base, tandis que les correspondances de cache ne coûtent que 10% du prix des tokens d’entrée de base.

Puis-je effacer manuellement le cache ?

Actuellement, il n’y a aucun moyen d’effacer manuellement le cache. Les préfixes mis en cache expirent automatiquement après un minimum de 5 minutes d’inactivité.

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

Vous pouvez surveiller les performances du cache en utilisant les champs cache_creation_input_tokens et cache_read_input_tokens dans la réponse API.

Qu'est-ce qui peut casser le cache ?

Voir Ce qui invalide le cache pour plus de détails sur l’invalidation du cache, incluant une liste de changements qui nécessitent la création d’une nouvelle entrée de cache.

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

La mise en cache des prompts est conçue avec de fortes mesures de confidentialité et de séparation des données :

1. Les clés de cache sont générées en utilisant un hachage cryptographique des prompts jusqu’au point de contrôle de cache. Cela signifie que seules les requêtes avec des prompts identiques peuvent accéder à un cache spécifique.

2. Les caches sont spécifiques à l’organisation. Les utilisateurs au sein de la même organisation peuvent accéder au même cache s’ils utilisent des prompts identiques, mais les caches ne sont pas partagés entre différentes organisations, même pour des prompts identiques.

3. Le mécanisme de mise en cache est conçu pour maintenir l’intégrité et la confidentialité de chaque conversation ou contexte unique.

4. Il est sûr d’utiliser cache_control n’importe où dans vos prompts. Pour l’efficacité des coûts, il est mieux d’exclure les parties très variables (par exemple, l’entrée arbitraire de l’utilisateur) de la mise en cache.

Ces mesures assurent que la mise en cache des prompts maintient la confidentialité et la sécurité des données tout en offrant des avantages de performance.

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

Oui, il est possible d’utiliser la mise en cache des prompts avec vos requêtes API Batches. Cependant, parce que les requêtes de lot asynchrones peuvent être traitées de manière concurrente et dans n’importe quel ordre, les correspondances de cache sont fournies sur une base de meilleur effort.

Le cache de 1 heure peut aider à améliorer vos correspondances de cache. La façon la plus rentable de l’utiliser est la suivante :

• Rassemblez un ensemble de requêtes de messages qui ont un préfixe partagé.
• Envoyez une requête de lot avec juste une seule requête qui a ce préfixe partagé et un bloc de cache de 1 heure. Cela sera écrit dans le cache de 1 heure.
• Dès que cela est terminé, soumettez le reste des requêtes. Vous devrez surveiller le travail pour savoir quand il se termine.

Ceci est typiquement mieux que d’utiliser le cache de 5 minutes simplement parce qu’il est courant que les requêtes de lot prennent entre 5 minutes et 1 heure pour se terminer. Nous considérons des façons d’améliorer ces taux de correspondance de cache et de rendre ce processus plus simple.

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

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

Utilisez simplement :

Python

python client.messages.create(...)

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

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 :

TypeScript

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

Utilisez simplement :

client.messages.create(...)