Mise en cache des invites

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-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
      },
      {
        "type": "text",
        "text": "<the entire contents of Pride and Prejudice>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

# Call the model again with the same inputs up to the cache checkpoint
curl https://api.anthropic.com/v1/messages # rest of input

{"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}

​

Comment fonctionne la mise en cache des invites

1. Le système vérifie si un préfixe d’invite, 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 l’invite complète et met en cache le préfixe une fois que la réponse commence.

• Les invites avec de nombreux exemples
• De grandes quantités de contexte ou d’informations générales
• Les tâches répétitives avec des instructions cohérentes
• Les longues conversations multi-tours

​

Tarification

​

Comment implémenter la mise en cache des invites

​

Modèles pris en charge

• Claude Opus 4.1
• Claude Opus 4
• Claude Sonnet 4.5
• Claude Sonnet 4
• Claude Sonnet 3.7
• Claude Haiku 4.5
• Claude Haiku 3.5
• Claude Haiku 3
• Claude Opus 3 (obsolète)

​

Structurer votre invite

​

Comment fonctionne la vérification automatique des préfixes

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 tous les blocs précédents dans la conversation de manière séquentielle. Cela signifie que le cache pour chaque bloc dépend de tout le contenu qui l’a précédé.
2. Vérification séquentielle rétroactive : Le système vérifie les accès au cache en travaillant à rebours à partir de votre point de rupture explicite, en vérifiant chaque bloc précédent dans l’ordre inverse. Cela garantit que vous obtenez l’accès au cache le plus long possible.
3. Fenêtre de recherche rétroactive 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 la vérification et passe au point de rupture explicite suivant (le cas échéant).

• Si vous envoyez le bloc 31 sans modifications aux blocs précédents : Le système vérifie le bloc 30 (correspondance !). Vous obtenez un accès au cache au bloc 30, et seul le bloc 31 nécessite un traitement.
• Si vous modifiez le bloc 25 et envoyez le bloc 31 : Le système vérifie à rebours du bloc 30 → 29 → 28… → 25 (pas de correspondance) → 24 (correspondance !). Puisque le bloc 24 n’a pas changé, vous obtenez un accès au cache au bloc 24, et seuls les blocs 25-30 nécessitent un retraitement.
• Si vous modifiez le bloc 5 et envoyez le bloc 31 : Le système vérifie à rebours du bloc 30 → 29 → 28… → 11 (vérification #20). Après 20 vérifications sans trouver de correspondance, il arrête la recherche. Puisque le bloc 5 est au-delà de la fenêtre de 20 blocs, aucun accès au cache ne se produit et tous les blocs nécessitent un retraitement. Cependant, si vous aviez défini un point de rupture cache_control explicite sur le bloc 5, le système continuerait à vérifier à partir de ce point de rupture : bloc 5 (pas de correspondance) → bloc 4 (correspondance !). Cela permet un accès au cache au bloc 4, démontrant pourquoi vous devriez placer des points de rupture avant le contenu modifiable.

​

Quand utiliser plusieurs points de rupture

• Mettre en cache différentes sections qui changent à des fréquences différentes (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 du contenu plus de 20 blocs avant votre point de rupture final
• Placer des points de rupture avant le contenu modifiable pour garantir des accès au cache même lorsque des modifications se produisent au-delà de la fenêtre de 20 blocs

​

Limitations du cache

• 1024 jetons pour Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude Sonnet 3.7 (obsolète) et Claude Opus 3 (obsolète)
• 4096 jetons pour Claude Haiku 4.5
• 2048 jetons pour Claude Haiku 3.5 et Claude Haiku 3

​

Comprendre les coûts des points de rupture de cache

• Écritures de cache : Lorsque du nouveau contenu est écrit dans le cache (25 % de plus que les jetons 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 jetons d’entrée de base)
• Jetons d’entrée réguliers : Pour tout contenu non mis en cache

​

Ce qui peut être mis en cache

• 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

​

Ce qui ne peut pas être mis en cache

• 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 aux côtés 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 des jetons d’entrée lorsqu’ils sont lus à partir du cache.
• Les blocs de sous-contenu (comme les citations) eux-mêmes ne peuvent pas être mis en cache directement. À la place, 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 la mise en cache des invites avec les citations efficacement 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

​

Suivi des performances du cache

• cache_creation_input_tokens : Nombre de jetons écrits dans le cache lors de la création d’une nouvelle entrée.
• cache_read_input_tokens : Nombre de jetons récupérés du cache pour cette demande.
• input_tokens : Nombre de jetons d’entrée qui n’ont pas été lus ou utilisés pour créer un cache.

​

Meilleures pratiques pour une mise en cache efficace

• Mettez en cache le contenu stable et réutilisable comme les instructions système, les informations générales, les grands contextes ou les définitions d’outils fréquentes.
• Placez le contenu mis en cache au début de l’invite pour de meilleures performances.
• Utilisez les points de rupture de cache de manière stratégique pour séparer différentes sections de préfixe pouvant être mises en cache.
• Définissez les points de rupture de cache à la fin des conversations et juste avant le contenu modifiable pour maximiser les taux d’accès au cache, en particulier lorsque vous travaillez avec des invites ayant plus de 20 blocs de contenu.
• Analysez régulièrement les taux d’accès au cache et ajustez votre stratégie selon les besoins.

​

Optimisation pour différents cas d’utilisation

• Agents conversationnels : Réduisez le coût et la latence pour les conversations prolongées, en particulier celles avec de longues instructions ou des documents téléchargés.
• Assistants de codage : Améliorez l’autocomplétion et les questions-réponses sur la base de code en gardant les sections pertinentes ou une version résumée de la base de code dans l’invite.
• Traitement de grands documents : Incorporez du matériel long complet, y compris des images, dans votre invite 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 l’invite, mais avec la mise en cache des invites, vous pouvez obtenir des performances encore meilleures 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 modifications de code itératives, où chaque étape nécessite généralement un nouvel appel API.
• Parlez à des livres, des articles, de la documentation, des transcriptions de podcasts et d’autres contenus longs : Donnez vie à n’importe quelle base de connaissances en intégrant le ou les documents entiers dans l’invite, et laissez les utilisateurs poser des questions.

​

Dépannage des problèmes courants

• Assurez-vous que les sections mises en cache sont identiques et marquées avec cache_control aux mêmes emplacements dans tous les appels
• 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 d’images restent cohérents entre les appels
• Validez que vous mettez en cache au moins le nombre minimum de jetons
• Le système vérifie automatiquement les accès au cache aux limites des blocs de contenu précédents (jusqu’à ~20 blocs avant votre point de rupture). Pour les invites avec plus de 20 blocs de contenu, vous devrez peut-être ajouter des paramètres cache_control supplémentaires plus tôt dans l’invite pour assurer que tout le contenu peut être mis en cache
• Vérifiez que les clés de vos blocs de contenu tool_use ont un ordre stable car certains langages (par exemple Swift, Go) randomisent l’ordre des clés lors de la conversion JSON, ce qui casse les caches

​

Mise en cache avec les blocs de réflexion

• Le cache reste valide lorsque seuls les résultats d’outils sont fournis en tant que 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

Demande 1 : Utilisateur : « Quel est le temps à Paris ? »
Réponse : [thinking_block_1] + [bloc tool_use 1]

Demande 2 :
Utilisateur : [« Quel est le temps à Paris ? »],
Assistant : [thinking_block_1] + [bloc tool_use 1],
Utilisateur : [tool_result_1, cache=True]
Réponse : [thinking_block_2] + [bloc texte 2]
# La demande 2 met en cache son contenu de demande (pas la réponse)
# Le cache inclut : message utilisateur, thinking_block_1, bloc tool_use 1 et tool_result_1

Demande 3 :
Utilisateur : [« Quel est le temps à Paris ? »],
Assistant : [thinking_block_1] + [bloc tool_use 1],
Utilisateur : [tool_result_1, cache=True],
Assistant : [thinking_block_2] + [bloc texte 2],
Utilisateur : [Réponse texte, cache=True]
# Le bloc utilisateur non-résultat d'outil entraîne l'ignorance de tous les blocs de réflexion
# Cette demande est traitée comme si les blocs de réflexion n'avaient jamais été présents

​

Stockage et partage du cache

• Isolation organisationnelle : Les caches sont isolés entre les organisations. Différentes organisations ne partagent jamais les caches, même si elles utilisent des invites identiques.
• Correspondance exacte : Les accès au cache nécessitent une correspondance à 100 % des segments d’invite, y compris tout le texte et les images jusqu’à et y compris le bloc marqué avec le contrôle de cache.
• Génération de jetons de sortie : La mise en cache des invites n’a aucun effet sur la génération de jetons de sortie. La réponse que vous recevez sera identique à ce que vous obtiendriez si la mise en cache des invites n’était pas utilisée.

​

Durée du cache d’1 heure

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

{
    "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,
        }
    }
}

​

Quand utiliser le cache d’1 heure

• Lorsque vous avez des invites susceptibles d’être utilisées moins fréquemment que toutes les 5 minutes, mais plus fréquemment que toutes les heures. Par exemple, lorsqu’un agent auxiliaire agentique prendra plus de 5 minutes, ou lorsque vous stockez 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 prochaines minutes.
• Lorsque la latence est importante et que vos invites de suivi peuvent être envoyées au-delà de 5 minutes.
• Lorsque vous souhaitez améliorer votre utilisation des limites de débit, car les accès au cache ne sont pas déduits de votre limite de débit.

​

Mélanger différents TTL

1. Position A : Le nombre de jetons au plus haut accès au cache (ou 0 s’il n’y a pas d’accès).
2. Position B : Le nombre de jetons au plus haut bloc cache_control d’1 heure après A (ou égal à A s’il n’en existe pas).
3. Position C : Le nombre de jetons au dernier bloc cache_control.

1. Jetons de lecture du cache pour A.
2. Jetons d’écriture de cache d’1 heure pour (B - A).
3. Jetons d’écriture de cache de 5 minutes pour (C - B).

​

Exemples de mise en cache des invites

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-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "You are an AI assistant tasked with analyzing legal documents."
        },
        {
            "type": "text",
            "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the key terms and conditions in this agreement?"
        }
    ]
}'

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-sonnet-4-5",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either celsius or fahrenheit"
                    }
                },
                "required": ["location"]
            }
        },
        # many more tools
        {
            "name": "get_time",
            "description": "Get the current time in a given time zone",
            "input_schema": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "The IANA time zone name, e.g. America/Los_Angeles"
                    }
                },
                "required": ["timezone"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather and time in New York?"
        }
    ]
}'

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-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
        {
            "type": "text",
            "text": "...long system prompt",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, can you tell me more about the solar system?",
                }
            ]
        },
        {
            "role": "assistant",
            "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Good to know."
                },
                {
                    "type": "text",
                    "text": "Tell me more about Mars.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

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-sonnet-4-5",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "search_documents",
            "description": "Search through the knowledge base",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query"
                    }
                },
                "required": ["query"]
            }
        },
        {
            "name": "get_document",
            "description": "Retrieve a specific document by ID",
            "input_schema": {
                "type": "object",
                "properties": {
                    "doc_id": {
                        "type": "string",
                        "description": "Document ID"
                    }
                },
                "required": ["doc_id"]
            },
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "system": [
        {
            "type": "text",
            "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
            "cache_control": {"type": "ephemeral"}
        },
        {
            "type": "text",
            "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Can you search for information about Mars rovers?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "tool_use",
                    "id": "tool_1",
                    "name": "search_documents",
                    "input": {"query": "Mars rovers"}
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "tool_1",
                    "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Yes, please tell me about the Perseverance rover specifically.",
                    "cache_control": {"type": "ephemeral"}
                }
            ]
        }
    ]
}'

​

FAQ

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

python client.messages.create(...)

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

client.messages.create(...)