Loading...
    • Guide du développeur
    • Référence API
    • MCP
    • Ressources
    • Notes de version
    Search...
    ⌘K
    Premiers pas
    Introduction à ClaudeDémarrage rapide
    Modèles et tarification
    Aperçu des modèlesChoisir un modèleNouveautés dans Claude 4.6Guide de migrationDépréciation des modèlesTarification
    Créer avec Claude
    Aperçu des fonctionnalitésUtiliser l'API MessagesGérer les raisons d'arrêtBonnes pratiques de prompting
    Capacités du modèle
    Extended thinkingAdaptive thinkingEffortMode rapide (aperçu de recherche)Sorties structuréesCitationsStreaming de messagesTraitement par lotsSupport PDFRésultats de rechercheSupport multilingueEmbeddingsVision
    Outils
    AperçuComment implémenter l'utilisation d'outilsOutil de recherche webOutil de récupération webOutil d'exécution de codeOutil de mémoireOutil BashOutil Computer useOutil d'éditeur de texte
    Infrastructure d'outils
    Recherche d'outilsAppel d'outils programmatiqueStreaming d'outils à granularité fine
    Gestion du contexte
    Fenêtres de contexteCompactionÉdition du contexteMise en cache des promptsComptage des tokens
    Fichiers et ressources
    API Files
    Agent Skills
    AperçuDémarrage rapideBonnes pratiquesSkills pour l'entrepriseUtiliser Skills avec l'API
    Agent SDK
    AperçuDémarrage rapideSDK TypeScriptTypeScript V2 (aperçu)SDK PythonGuide de migration
    MCP dans l'API
    Connecteur MCPServeurs MCP distants
    Claude sur des plateformes tierces
    Amazon BedrockMicrosoft FoundryVertex AI
    Ingénierie des prompts
    AperçuGénérateur de promptsUtiliser des modèles de promptsAméliorateur de promptsÊtre clair et directUtiliser des exemples (prompting multi-shots)Laisser Claude réfléchir (CoT)Utiliser des balises XMLDonner un rôle à Claude (prompts système)Chaîner des prompts complexesConseils pour le contexte longConseils pour extended thinking
    Tester et évaluer
    Définir les critères de succèsDévelopper des cas de testUtiliser l'outil d'évaluationRéduire la latence
    Renforcer les garde-fous
    Réduire les hallucinationsAugmenter la cohérence des résultatsAtténuer les jailbreaksRefus en streamingRéduire les fuites de promptsGarder Claude dans le rôle
    Administration et surveillance
    Aperçu de l'API AdminRésidence des donnéesEspaces de travailAPI d'utilisation et de coûtsAPI Claude Code AnalyticsZéro rétention de données
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    Gestion du contexte

    Mise en cache des prompts

    Optimisez votre utilisation de l'API en mettant en cache les préfixes de prompts pour réduire les coûts et la latence.

    Was this page helpful?

    • Fonctionnement de la mise en cache des prompts
    • Tarification
    • Modèles pris en charge
    • Mise en cache automatique
    • Fonctionnement de la mise en cache automatique dans les conversations multi-tours
    • Prise en charge du TTL
    • Combinaison avec la mise en cache au niveau des blocs
    • Ce qui reste identique
    • Cas limites
    • Points de rupture de cache explicites
    • Structurer votre prompt
    • Comprendre les coûts des points de rupture de cache
    • Stratégies et considérations de mise en cache
    • Limitations du 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
    • Mise en cache avec les blocs de réflexion
    • Stockage et partage du cache
    • Meilleures pratiques pour une mise en cache efficace
    • Optimisation pour différents cas d'utilisation
    • Résolution des problèmes courants
    • Durée de cache d'1 heure
    • Quand utiliser le cache d'1 heure
    • Mélange de différents TTL
    • Exemples de mise en cache des prompts
    • Conservation des données
    • FAQ

    La mise en cache des prompts optimise votre utilisation de l'API en permettant de reprendre à partir de préfixes spécifiques dans vos prompts. Cela réduit considérablement le temps de traitement et les coûts pour les tâches répétitives ou les prompts avec des éléments constants.

    This feature qualifies for Zero Data Retention (ZDR) with limited technical retention. See the Data retention section for details on what is retained and why.

    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 à mesure que les conversations se développent. Idéal pour les conversations multi-tours où l'historique des messages en croissance 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 mis en cache.

    La façon la plus simple de commencer est avec la mise en cache automatique :

    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-6",
        "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."
          }
        ]
      }'

    Avec la mise en cache automatique, le système met en cache tout le contenu jusqu'au dernier bloc pouvant être mis en cache inclus. Lors des requêtes suivantes avec le même préfixe, le contenu mis en cache est réutilisé automatiquement.


    Fonctionnement de la mise en cache des prompts

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

    1. Le système vérifie si un préfixe de prompt, jusqu'à un point 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 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 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é.

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

    Pour plus d'informations, voir Durée de cache d'1 heure.

    La mise en cache des prompts met en cache le préfixe complet

    La mise en cache des prompts référence le 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 tarifaire. Le tableau ci-dessous indique le prix par million de tokens pour chaque modèle pris en charge :

    ModelBase Input Tokens5m Cache Writes1h Cache WritesCache Hits & RefreshesOutput Tokens
    Claude Opus 4.6$5 / MTok$6.25 / MTok$10 / MTok$0.50 / MTok$25 / MTok
    Claude Opus 4.5$5 / MTok$6.25 / MTok$10 / MTok$0.50 / MTok$25 / MTok
    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.6

    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 d'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

    Ces multiplicateurs s'accumulent avec d'autres modificateurs de tarification tels que la remise de l'API Batch, la tarification des longs contextes et la résidence des données. Voir tarification pour tous les détails.


    Modèles pris en charge

    La mise en cache des prompts (automatique et explicite) est actuellement prise en charge sur :

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

    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 de votre corps de requête. Le système applique automatiquement le point de rupture de cache au dernier bloc pouvant être mis en cache.

    Fonctionnement de la mise en cache automatique dans les conversations multi-tours

    Avec la mise en cache automatique, le point de cache avance automatiquement à mesure que les conversations se développent. Chaque nouvelle requête met en cache tout jusqu'au dernier bloc pouvant être mis en cache, et le contenu précédent est lu depuis le cache.

    RequêteContenuComportement du cache
    Requête 1System
    + User(1) + Asst(1)
    + User(2) ◀ cache
    Tout est écrit dans le cache
    Requête 2System
    + User(1) + Asst(1)
    + User(2) + Asst(2)
    + User(3) ◀ cache
    System jusqu'à User(2) lu depuis le cache ;
    Asst(2) + User(3) écrits dans le cache
    Requête 3System
    + User(1) + Asst(1)
    + User(2) + Asst(2)
    + User(3) + Asst(3)
    + User(4) ◀ cache
    System jusqu'à User(3) lu depuis le cache ;
    Asst(3) + User(4) écrits dans 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 à mesure que la conversation se développe.

    Prise en charge du TTL

    Par défaut, la mise en cache automatique utilise un TTL de 5 minutes. Vous pouvez spécifier un TTL d'1 heure à 2 fois le prix des tokens d'entrée de base :

    "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 des points de rupture explicites pour mettre en cache votre prompt système et vos outils indépendamment, tandis que la mise en cache automatique gère la conversation :

    {
      "model": "claude-opus-4-6",
      "max_tokens": 1024,
      "cache_control": {"type": "ephemeral"},
      "system": [
        {
          "type": "text",
          "text": "You are a helpful assistant.",
          "cache_control": {"type": "ephemeral"}
        }
      ],
      "messages": [...]
    }

    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 de contexte et la fenêtre de recherche arrière de 20 blocs s'appliquent de la même façon 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 disponible 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 pour trouver le bloc éligible le plus proche. Si aucun n'est trouvé, la mise en cache est ignorée.

    La mise en cache automatique est disponible sur l'API Claude et Azure AI Foundry (aperçu). La prise en charge d'Amazon Bedrock et de Google Vertex AI arrivera ultérieurement.


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

    Fonctionnement de 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 la séquence la plus longue de blocs mis en cache correspondants. Comprendre comment cela fonctionne vous aide à optimiser votre stratégie de mise en cache.

    Trois principes fondamentaux :

    1. Les clés de cache sont cumulatives : Lorsque vous mettez explicitement en cache un bloc avec cache_control, la clé de hachage du cache est générée en hachant séquentiellement tous les blocs précédents de la conversation. Cela signifie que le cache pour chaque bloc dépend de tout le contenu qui le précède.

    2. Vérification séquentielle en arrière : Le système vérifie les correspondances de cache en remontant depuis votre point de rupture explicite, en vérifiant chaque bloc précédent dans l'ordre inverse. Cela garantit que vous obtenez la correspondance de cache la plus longue possible.

    3. Fenêtre de recherche arrière de 20 blocs : Le système ne vérifie que jusqu'à 20 blocs avant chaque point de rupture cache_control explicite. Après avoir vérifié 20 blocs sans correspondance, il arrête de vérifier et passe au prochain point de rupture explicite (le cas échéant).

    Exemple : Comprendre la fenêtre de recherche arrière

    Considérez une conversation avec 30 blocs de contenu où vous définissez cache_control uniquement sur le bloc 30 :

    • Si vous envoyez le bloc 31 sans modifications des blocs précédents : Le système vérifie le bloc 30 (correspondance !). Vous obtenez une correspondance de cache au bloc 30, et seul le bloc 31 doit être traité.

    • Si vous modifiez le bloc 25 et envoyez le bloc 31 : Le système vérifie en arrière depuis le bloc 30 → 29 → 28... → 25 (pas de correspondance) → 24 (correspondance !). Puisque le bloc 24 n'a pas changé, vous obtenez une correspondance de cache au bloc 24, et seuls les blocs 25 à 30 doivent être retraités.

    • Si vous modifiez le bloc 5 et envoyez le bloc 31 : Le système vérifie en arrière depuis le bloc 30 → 29 → 28... → 11 (vérification n°20). Après 20 vérifications sans trouver de correspondance, il arrête de chercher. Puisque le bloc 5 est au-delà de la fenêtre de 20 blocs, aucune correspondance de cache ne se produit et tous les blocs doivent être retraités. Cependant, si vous aviez défini un point de rupture cache_control explicite sur le bloc 5, le système continuerait à vérifier depuis ce point de rupture : bloc 5 (pas de correspondance) → bloc 4 (correspondance !). Cela permet une correspondance de cache au bloc 4, démontrant pourquoi vous devriez placer des points de rupture avant le contenu modifiable.

    Point clé : Définissez toujours un point de rupture de cache explicite à la fin de votre conversation pour maximiser vos chances de correspondances de cache. De plus, définissez des points de rupture juste avant les blocs de contenu susceptibles d'être modifiables pour garantir que ces sections peuvent être mises en cache indépendamment.

    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 la mise en cache pour du contenu situé à plus de 20 blocs avant votre dernier point de rupture
    • Placer des points de rupture avant le contenu modifiable pour garantir des correspondances de cache même lorsque des modifications se produisent au-delà de la fenêtre de 20 blocs

    Limitation importante : Si votre prompt a plus de 20 blocs de contenu avant votre point de rupture de cache, et que vous modifiez du contenu antérieur à ces 20 blocs, vous n'obtiendrez pas de correspondance de cache à moins d'ajouter des points de rupture explicites supplémentaires plus proches de ce contenu.

    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 êtes uniquement facturé 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 des tokens d'entrée de base)
    • Les tokens d'entrée réguliers : Pour tout contenu non mis en cache

    Ajouter plus de points de rupture cache_control n'augmente pas vos coûts - vous payez toujours le même montant en fonction du contenu réellement mis en cache et lu. Les points de rupture vous donnent simplement le contrôle sur les sections pouvant être mises en cache indépendamment.


    Stratégies et considérations de mise en cache

    Limitations du cache

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

    • 4096 tokens pour Claude Opus 4.6, Claude Opus 4.5
    • 2048 tokens pour Claude Sonnet 4.6
    • 1024 tokens pour Claude Sonnet 4.5, Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4 et Claude Sonnet 3.7 (déprécié)
    • 4096 tokens pour Claude Haiku 4.5
    • 2048 tokens pour Claude Haiku 3.5 (déprécié) 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. Toutes les requêtes visant à mettre en cache moins que ce nombre de tokens seront traitées sans mise en cache. Pour voir si un prompt a été mis en cache, consultez les champs d'utilisation de la réponse.

    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 correspondances de cache pour des requêtes parallèles, attendez la première réponse avant d'envoyer les requêtes suivantes.

    Actuellement, "ephemeral" est le seul type de cache pris en charge, qui a par défaut une durée de vie de 5 minutes.

    Ce qui peut être mis en cache

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

    • Les outils : Les définitions d'outils dans le tableau tools
    • Les messages système : Les blocs de contenu dans le tableau system
    • Les messages texte : Les blocs de contenu dans le tableau messages.content, pour les tours utilisateur et assistant
    • Les images et documents : Les blocs de contenu dans le tableau messages.content, dans les tours utilisateur
    • L'utilisation d'outils et les 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'autre contenu lorsqu'ils apparaissent dans les tours 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. 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.

    Ce qui changeCache des outilsCache systèmeCache des messagesImpact
    Définitions d'outils✘✘✘La modification des définitions d'outils (noms, descriptions, paramètres) invalide l'intégralité du cache
    Activation de la recherche web✓✘✘L'activation/désactivation de la recherche web modifie le prompt système
    Activation des citations✓✘✘L'activation/désactivation des citations modifie le prompt système
    Paramètre de vitesse✓✘✘Le basculement entre speed: "fast" et la vitesse standard invalide les caches système et des messages

    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 l'é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 depuis le cache pour cette requête.
    • input_tokens : Nombre de tokens d'entrée qui n'ont pas été lus depuis le cache ou utilisés pour créer un cache (c'est-à-dire les tokens après le dernier point de rupture de cache).

    Comprendre la répartition des tokens

    Le champ input_tokens représente uniquement les tokens qui viennent après le dernier point de rupture de cache dans votre requête - pas tous les tokens d'entrée que vous avez envoyés.

    Pour calculer le total des tokens d'entrée :

    total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

    Explication spatiale :

    • cache_read_input_tokens = tokens avant le point de rupture déjà mis en cache (lectures)
    • cache_creation_input_tokens = tokens avant le point de rupture en cours de mise en cache (écritures)
    • input_tokens = tokens après votre dernier point de rupture (non éligibles au cache)

    Exemple : Si vous avez une requête avec 100 000 tokens de contenu mis en cache (lus depuis le cache), 0 token de nouveau contenu en cours de mise en cache, et 50 tokens dans votre message utilisateur (après le point de rupture de cache) :

    • cache_read_input_tokens : 100 000
    • : 0

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

    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 effectuez des appels API ultérieurs avec des résultats d'outils. Cela se produit généralement lors de l'utilisation d'outils lorsque vous transmettez des 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. C'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 des résultats d'outils sont fournis comme messages utilisateur
    • Le cache est invalidé lorsque du contenu utilisateur non-résultat d'outil est ajouté, ce qui entraîne 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 :

    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]
    # Non-tool-result user block causes all thinking blocks to be ignored
    # This request is processed as if thinking blocks were never present

    Lorsqu'un bloc utilisateur non-résultat d'outil est inclus, il désigne une nouvelle boucle 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 sur la réflexion étendue.

    Stockage et partage du cache

    À partir du 5 février 2026, la mise en cache des prompts utilisera l'isolation au niveau de l'espace de travail au lieu de l'isolation au niveau de l'organisation. Les caches seront isolés par espace de travail, garantissant la séparation des données entre les espaces de travail au sein d'une même organisation. Ce changement s'applique à l'API Claude et à Azure AI Foundry (aperçu) ; Amazon Bedrock et Google Vertex AI maintiendront l'isolation du cache au niveau de l'organisation. Si vous utilisez plusieurs espaces de travail, révisez votre stratégie de mise en cache pour tenir compte de ce changement.

    • Isolation de l'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 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 sera identique à ce que vous obtiendriez si la mise en cache des prompts n'était pas utilisée.

    Meilleures 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 la gestion des points de rupture.
    • Utilisez les points de rupture explicites au niveau des blocs lorsque vous devez mettre en cache différentes sections avec des fréquences de modification différentes.
    • Mettez en cache le contenu stable et réutilisable comme les instructions système, les informations de fond, les grands contextes ou les définitions d'outils fréquentes.
    • Placez le contenu mis en cache au début du prompt pour de meilleures performances.
    • Utilisez les points de rupture de cache de manière stratégique pour séparer différentes sections de préfixes pouvant être mises en cache.
    • Définissez des points de rupture de cache à la fin des conversations et juste avant le contenu modifiable pour maximiser les taux de correspondance de cache, surtout lorsque vous travaillez avec des prompts ayant plus de 20 blocs de contenu.
    • Analysez régulièrement les taux de correspondance de cache et ajustez votre stratégie selon les besoins.

    Optimisation pour différents cas d'utilisation

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

    • Agents conversationnels : Réduisez les coûts et la latence pour les conversations prolongées, notamment celles avec de longues instructions ou des documents téléchargé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 grands documents : Incorporez du matériel long complet 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 ou deux exemples dans le prompt, mais avec la mise en cache des prompts, vous pouvez obtenir de meilleures performances en incluant 20+ exemples diversifiés 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 modifications de code itératives, où chaque étape nécessite généralement un nouvel appel API.
    • Discuter 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(s) document(s) entier(s) dans le prompt et en laissant les utilisateurs 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 dans la durée de vie du cache (5 minutes par défaut)
    • Vérifiez que tool_choice et l'utilisation des 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 des blocs de contenu précédents (jusqu'à ~20 blocs avant votre point de rupture). 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 garantir que tout le contenu peut être mis en cache
    • Vérifiez que les clés dans 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

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


    Durée de cache d'1 heure

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

    Pour utiliser le cache étendu, incluez ttl dans la définition cache_control comme ceci :

    "cache_control": {
      "type": "ephemeral",
      "ttl": "1h"
    }

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

    {
      "usage": {
        "input_tokens": 2048,
        "cache_read_input_tokens": 1800,
        "cache_creation_input_tokens": 248,
        "output_tokens": 503,
    
        "cache_creation": {
          "ephemeral_5m_input_tokens": 456,
          "ephemeral_1h_input_tokens": 100
        }
      }
    }

    Notez que le champ actuel cache_creation_input_tokens est égal à la somme des valeurs dans l'objet cache_creation.

    Quand utiliser le cache d'1 heure

    Si vous avez des prompts utilisés à une cadence régulière (c'est-à-dire des prompts système utilisés plus fréquemment que toutes les 5 minutes), continuez à utiliser le cache de 5 minutes, car il continuera à être actualisé sans frais supplémentaires.

    Le cache d'1 heure est mieux utilisé dans les scénarios suivants :

    • Lorsque vous avez des prompts susceptibles d'être utilisés moins fréquemment que toutes les 5 minutes, mais plus fréquemment que toutes les heures. Par exemple, lorsqu'un agent secondaire agentique 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 correspondances de cache ne sont pas déduites de votre limite de débit.

    Le cache de 5 minutes et le cache d'1 heure se comportent de la même façon en ce qui concerne la latence. Vous verrez généralement un temps jusqu'au premier token amélioré pour les longs documents.

    Mélange de différents TTL

    Vous pouvez utiliser des contrôles de cache d'1 heure et de 5 minutes dans la même requête, mais avec une contrainte importante : les entrées de cache avec un TTL plus long doivent apparaître avant les TTL plus courts (c'est-à-dire qu'une entrée de cache d'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 si aucune correspondance).
    2. Position B : Le nombre de tokens au bloc cache_control d'1 heure le plus élevé après A (ou égal à A si aucun n'existe).
    3. Position C : Le nombre de tokens au dernier bloc cache_control.

    Si B et/ou C sont supérieurs à 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. Les tokens de lecture de cache pour A.
    2. Les tokens d'écriture de cache d'1 heure pour (B - A).
    3. Les tokens d'écriture de cache de 5 minutes pour (C - B).

    Voici 3 exemples. Cela 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, indiquée dans les cases colorées, en conséquence. Diagramme de mélange de TTL


    Exemples de mise en cache des prompts

    Pour vous aider à démarrer avec la mise en cache des prompts, nous avons préparé un cookbook sur la mise en cache des prompts avec des exemples détaillés et des bonnes pratiques.

    Ci-dessous, nous avons inclus plusieurs extraits de code qui illustrent différents 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 invites stocke les représentations KV (clé-valeur) du cache et les hachages cryptographiques du contenu mis en cache, mais ne stocke pas le texte brut des invites ou des réponses. Les entrées mises en cache ont une durée de vie minimale de 5 minutes (standard) ou 60 minutes (étendue). Les entrées de cache sont isolées entre les organisations. Étant donné qu'Anthropic ne stocke pas le texte brut des invites ou des réponses, cette fonctionnalité peut convenir aux clients qui nécessitent des engagements de conservation des données de type ZDR.

    Pour l'éligibilité ZDR sur toutes les fonctionnalités, voir API et conservation des données.


    FAQ

    $3 / MTok
    $3.75 / MTok
    $6 / MTok
    $0.30 / MTok
    $15 / MTok
    Claude Sonnet 4.5$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
    Claude Sonnet 4$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
    Claude Sonnet 3.7 (deprecated)$3 / MTok$3.75 / MTok$6 / MTok$0.30 / MTok$15 / MTok
    Claude Haiku 4.5$1 / MTok$1.25 / MTok$2 / MTok$0.10 / MTok$5 / 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
    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-6",
        "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?"}
        ]
      }'
    Choix d'outil✓✓✘Les modifications du paramètre tool_choice n'affectent que les blocs de messages
    Images✓✓✘L'ajout/suppression d'images n'importe où dans le prompt affecte les blocs de messages
    Paramètres de réflexion✓✓✘Les modifications des paramètres de réflexion étendue (activation/désactivation, budget) affectent les blocs de messages
    Résultats non-outils transmis aux requêtes de réflexion étendue✓✓✘Lorsque des résultats non-outils sont transmis dans des requêtes alors 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 du contexte qui suivent ces blocs de réflexion sont retirés du cache. Pour plus de détails, voir Mise en cache avec les blocs de réflexion.
    cache_creation_input_tokens
  1. input_tokens : 50
  2. Total des tokens d'entrée traités : 100 050 tokens
  3. C'est important pour comprendre à la fois les coûts et les limites de débit, car input_tokens sera généralement beaucoup plus petit que votre entrée totale lorsque vous utilisez efficacement la mise en cache.