---
title: Mise en cache des prompts
url: https://platform.claude.com/docs/fr/build-with-claude/prompt-caching
description: Mettez en cache les préfixes de prompts avec `cache_control` pour réduire les coûts et la latence, grâce à la mise en cache automatique ou à des points d'arrêt explicites avec des TTL de 5 minutes ou d'1 heure.
featureMetadata:
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements). Vos prompts et les sorties de Claude ne sont pas stockés. Les représentations du cache KV et les hachages cryptographiques sont conservés en mémoire pendant la durée de vie du cache et supprimés rapidement après son expiration.
supportedModels:
- claude-fable-5-2
- claude-mythos-5-2
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-mythos-preview
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-haiku-5-5
- claude-haiku-4-5-20251001
- claude-opus-4-8
- claude-opus-4-7
- claude-opus-4-6
- claude-sonnet-4-6
- claude-opus-4-5-20251101
- claude-sonnet-4-5-20250929
supportedPlatforms:
Claude API: stable
Claude Platform on AWS: stable
Claude Models on Google Cloud (Anthropic managed): stable
Amazon Bedrock: stable
Amazon Bedrock (InvokeModel): stable
Claude Models on Google Cloud (Google managed): stable
Microsoft Foundry: stable
---
**Prise en charge de l’API** : L’utilisation varie selon le produit.
* **Messages API** : Activez-la avec `cache_control`, au niveau supérieur ou sur des blocs.
* **Managed Agents** : Toujours activé. Les entrées du cache ont une durée de vie de 5 minutes par défaut, et les lectures et écritures du cache apparaissent dans l’utilisation de la session.
Le « prompt caching » (mise en cache des prompts) optimise votre utilisation de l’API en permettant à l’API de reprendre à partir de préfixes spécifiques dans vos prompts. Cela réduit considérablement le temps de traitement et les coûts pour les tâches répétitives ou les prompts comportant des éléments constants.
Il existe deux façons d’activer la mise en cache des prompts :
* **[Mise en cache automatique](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#automatic-caching) :** Ajoutez un seul champ `cache_control` au niveau supérieur de votre requête. Le système applique automatiquement le « cache breakpoint » (point d’arrêt de cache) au dernier bloc pouvant être mis en cache et le fait avancer à mesure que les conversations s’allongent. Idéal pour les conversations multi-tours où l’historique croissant des messages doit être mis en cache automatiquement.
* **[Points d’arrêt de cache explicites](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#explicit-cache-breakpoints) :** Placez `cache_control` directement sur des blocs de contenu individuels pour un contrôle précis de ce qui est mis en cache.
La manière la plus simple de commencer est d’utiliser la mise en cache automatique :
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
"messages": [
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
cache_control:
type: ephemeral
system: >-
You are an AI assistant tasked with analyzing literary works. Your goal is
to provide insightful commentary on themes, characters, and writing style.
messages:
- role: user
content: Analyze the major themes in Pride and Prejudice.
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages=[
{
"role": "user",
"content": "Analyze the major themes in 'Pride and Prejudice'.",
}
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: { type: "ephemeral" },
system:
"You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages: [
{
role: "user",
content: "Analyze the major themes in 'Pride and Prejudice'."
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
CacheControl = new CacheControlEphemeral(),
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 =
[
new UserMessageParam { Content = "Analyze the major themes in 'Pride and Prejudice'." }
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
System: []anthropic.TextBlockParam{
{Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in 'Pride and Prejudice'.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.cacheControl(CacheControlEphemeral.builder().build())
.system("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.")
.addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")
.build();
Message message = client.messages().create(params);
IO.println(message.usage());
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
use Anthropic\Messages\Model;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => "Analyze the major themes in 'Pride and Prejudice'."]
],
model: Model::CLAUDE_OPUS_5_5,
cacheControl: CacheControlEphemeral::with(),
system: 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.',
);
echo json_encode($response->usage);
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
cache_control: {type: "ephemeral"},
system_: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
messages: [
{
role: "user",
content: "Analyze the major themes in 'Pride and Prejudice'."
}
]
)
puts response.usage
```
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 ayant 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 d’arrêt de cache spécifié, est déjà en cache à partir d’une requête récente.
2. S’il est trouvé, il utilise la version mise en cache, ce qui réduit le temps de traitement et les coûts.
3. Sinon, il traite le prompt complet et met en cache le préfixe dès que la réponse commence.
Ceci est particulièrement utile pour :
* Les prompts comportant 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 rafraîchi sans coût supplémentaire chaque fois que le contenu mis en cache est utilisé.
La durée de vie est mesurée à partir du début de la requête qui écrit ou lit l’entrée de cache, et non à partir de la fin de sa réponse. Le temps passé à générer une réponse est décompté de la durée de vie : si une réponse met 4 minutes à être diffusée en streaming, une requête de suivi qui réutilise le même préfixe mis en cache doit démarrer dans un délai d’environ 1 minute après la fin de cette réponse.
Si vous trouvez que 5 minutes est trop court, Anthropic propose également une durée de cache d’1 heure [moyennant un coût supplémentaire](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#pricing).
Pour plus d’informations, consultez [Durée de cache d’1 heure](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#1-hour-cache-duration).
**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é par `cache_control` inclus.
***
## Tarification
La mise en cache des prompts dispose de sa propre tarification. Le tableau suivant indique 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 and refreshes | Output tokens |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------- | :-------------- | :-------------- | :----------------------- | :------------ |
| Claude Fable 5.2 | $8 / MTok | $10 / MTok | $16 / MTok | $0.20 / MTok1 | $40 / MTok |
| Claude Mythos 5.2 ([limited availability](https://support.claude.com/en/articles/14604842)) | $8 / MTok | $10 / MTok | $16 / MTok | $0.20 / MTok1 | $40 / MTok |
| Claude Fable 5.1 | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok |
| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $0.25 / MTok1 | $50 / MTok |
| Claude Fable 5 | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842)) | $10 / MTok | $12.50 / MTok | $20 / MTok | $1 / MTok | $50 / MTok |
| Claude Opus 5.5 | $4 / MTok | $5 / MTok | $8 / MTok | $0.20 / MTok2 | $20 / MTok |
| Claude Opus 5 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.8 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| Claude Opus 4.7 | $5 / MTok | $6.25 / MTok | $10 / MTok | $0.50 / MTok | $25 / MTok |
| 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 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/fr/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Opus 4 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/fr/about-claude/model-deprecations)) | $15 / MTok | $18.75 / MTok | $30 / MTok | $1.50 / MTok | $75 / MTok |
| Claude Sonnet 5.5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.10 / MTok2 | $10 / MTok |
| Claude Sonnet 5 | $2 / MTok | $2.50 / MTok | $4 / MTok | $0.20 / MTok | $10 / MTok |
| Claude Sonnet 4.6 | $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 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/fr/about-claude/model-deprecations)) | $3 / MTok | $3.75 / MTok | $6 / MTok | $0.30 / MTok | $15 / MTok |
| Claude Haiku 5.5 (for prompts up to 100,000 tokens) | $0.10 / MTok | $0.125 / MTok | $0.20 / MTok | $0.01 / MTok | $0.50 / MTok |
| Claude Haiku 5.5 (for prompts over 100,000 tokens) | $0.50 / MTok | $0.625 / MTok | $1 / MTok | $0.05 / MTok | $2.50 / MTok |
| Claude Haiku 4.5 | $1 / MTok | $1.25 / MTok | $2 / MTok | $0.10 / MTok | $5 / MTok |
*1 Cache hits and refreshes on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, and Claude Mythos 5.1 are priced at 0.025x the base input price.*
*2 Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.*
*All other models use the standard 0.1x multiplier.*
Le tableau précédent reflète les multiplicateurs de tarification suivants pour la mise en cache des prompts :
* Les tokens d’écriture en cache avec un TTL de 5 minutes coûtent 1,25 fois le prix de base des tokens d’entrée.
* Les tokens d’écriture en cache avec un TTL d’1 heure coûtent 2 fois le prix de base des tokens d’entrée.
* Les tokens de lecture du cache coûtent 0,1 fois le prix de base des tokens d’entrée (consultez la note de bas de tableau pour les exceptions par modèle).
Ces multiplicateurs se cumulent avec d’autres modificateurs de tarification tels que la remise de l’API Batch, la [tarification du contexte long](https://platform.claude.com/docs/fr/about-claude/pricing#long-context-pricing) et la résidence des données. Sur un modèle dont le prix dépend de la longueur du prompt, les lectures et écritures en cache sont comptabilisées dans la longueur du prompt d’une requête. Consultez [Tarification](https://platform.claude.com/docs/fr/about-claude/pricing) pour tous les détails.
***
## Modèles pris en charge
La mise en cache des prompts (automatique et explicite) est prise en charge sur tous les [modèles Claude actifs](https://platform.claude.com/docs/fr/models/overview).
***
## Mise en cache automatique
La mise en cache automatique est la manière la plus simple d’activer la mise en cache des prompts. Au lieu de placer `cache_control` sur des blocs de contenu individuels, ajoutez un seul champ `cache_control` au niveau supérieur du corps de votre requête. Le système applique automatiquement le point d’arrêt de cache au dernier bloc pouvant être mis en cache.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "You are a helpful assistant that remembers our conversation.",
"messages": [
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{"role": "assistant", "content": "Nice to meet you, Alex! How can I help with your ML work today?"},
{"role": "user", "content": "What did I say I work on?"}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
cache_control:
type: ephemeral
system: You are a helpful assistant that remembers our conversation.
messages:
- role: user
content: My name is Alex. I work on machine learning.
- role: assistant
content: Nice to meet you, Alex! How can I help with your ML work today?
- role: user
content: What did I say I work on?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are a helpful assistant that remembers our conversation.",
messages=[
{"role": "user", "content": "My name is Alex. I work on machine learning."},
{
"role": "assistant",
"content": "Nice to meet you, Alex! How can I help with your ML work today?",
},
{"role": "user", "content": "What did I say I work on?"},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
cache_control: { type: "ephemeral" },
system: "You are a helpful assistant that remembers our conversation.",
messages: [
{ role: "user", content: "My name is Alex. I work on machine learning." },
{
role: "assistant",
content: "Nice to meet you, Alex! How can I help with your ML work today?"
},
{ role: "user", content: "What did I say I work on?" }
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
CacheControl = new CacheControlEphemeral(),
System = "You are a helpful assistant that remembers our conversation.",
Messages =
[
new UserMessageParam { Content = "My name is Alex. I work on machine learning." },
new AssistantMessageParam
{
Content = "Nice to meet you, Alex! How can I help with your ML work today?"
},
new UserMessageParam { Content = "What did I say I work on?" }
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
System: []anthropic.TextBlockParam{
{Text: "You are a helpful assistant that remembers our conversation."},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("My name is Alex. I work on machine learning.")),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("Nice to meet you, Alex! How can I help with your ML work today?")),
anthropic.NewUserMessage(anthropic.NewTextBlock("What did I say I work on?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.cacheControl(CacheControlEphemeral.builder().build())
.system("You are a helpful assistant that remembers our conversation.")
.addUserMessage("My name is Alex. I work on machine learning.")
.addAssistantMessage("Nice to meet you, Alex! How can I help with your ML work today?")
.addUserMessage("What did I say I work on?")
.build();
Message message = client.messages().create(params);
IO.println(message.usage());
}
```
```php PHP
use Anthropic\Messages\CacheControlEphemeral;
use Anthropic\Messages\Model;
// ...
$client = new Client();
$response = $client->messages->create(
maxTokens: 1024,
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?'],
],
model: Model::CLAUDE_OPUS_5_5,
cacheControl: CacheControlEphemeral::with(),
system: 'You are a helpful assistant that remembers our conversation.',
);
echo json_encode($response->usage);
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
cache_control: {type: "ephemeral"},
system_: "You are a helpful assistant that remembers our conversation.",
messages: [
{role: "user", content: "My name is Alex. I work on machine learning."},
{role: "assistant", content: "Nice to meet you, Alex! How can I help with your ML work today?"},
{role: "user", content: "What did I say I work on?"}
]
)
puts response.usage
```
### 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 s’allongent. Chaque nouvelle requête met en cache tout le contenu jusqu’au dernier bloc pouvant être mis en cache, et le contenu précédent est lu depuis le cache.
| Requête | Contenu | Comportement du cache |
| --------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Requête 1 | System
+ User(1) + Asst(1)
+ **User(2)** ◀ cache | Tout est écrit dans le cache |
| Requête 2 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ **User(3)** ◀ cache | De System à User(2) lu depuis le cache ;
Asst(2) + User(3) écrits dans le cache |
| Requête 3 | System
+ User(1) + Asst(1)
+ User(2) + Asst(2)
+ User(3) + Asst(3)
+ **User(4)** ◀ cache | De System à User(3) lu depuis le cache ;
Asst(3) + User(4) écrits dans le cache |
Le point d’arrêt 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 s’allonge.
### 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 de base des tokens d’entrée :
```json
{ "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 d’arrêt de cache explicites](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#explicit-cache-breakpoints). Lorsqu’ils sont utilisés ensemble, le point d’arrêt de cache automatique occupe l’un des 4 emplacements de point d’arrêt disponibles.
Cela vous permet de combiner les deux approches. Par exemple, utilisez un point d’arrêt explicite pour mettre en cache votre invite système, tandis que la mise en cache automatique gère la conversation :
```json
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": { "type": "ephemeral" },
"system": [
{
"type": "text",
"text": "You are a helpful assistant.",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What are the key terms?" }]
}
```
### Ce qui reste identique
La mise en cache automatique utilise la même infrastructure de mise en cache sous-jacente. La tarification, les seuils minimaux de tokens, les exigences d’ordre du contexte et la fenêtre de rétrospection de 20 blocs s’appliquent tous de la même manière qu’avec les points d’arrêt explicites.
### Cas limites
* Si le dernier bloc possède déjà un `cache_control` explicite avec le même TTL, la mise en cache automatique n’a aucun effet.
* Si le dernier bloc possède un `cache_control` explicite avec un TTL différent, l’API renvoie une erreur 400.
* Si 4 points d’arrêt explicites au niveau des blocs existent déjà, l’API renvoie une erreur 400 (aucun emplacement restant pour la mise en cache automatique).
* Si le dernier bloc n’est pas éligible comme cible de point d’arrêt 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 toutes les plateformes, à l’exception de l’intégration héritée [Amazon Bedrock (Opus 4.6 et versions antérieures)](https://platform.claude.com/docs/fr/build-with-claude/claude-on-amazon-bedrock-legacy). Sur cette intégration, l’API renvoie une erreur 400 pour un champ `cache_control` de niveau supérieur ; utilisez donc plutôt des [points d’arrêt de cache explicites](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#explicit-cache-breakpoints).
***
## Points d’arrêt de cache explicites
Pour un meilleur contrôle de la mise en cache, vous pouvez placer `cache_control` directement sur des blocs de contenu individuels. Cela 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 de 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 à mettre en cache à l’aide du paramètre `cache_control`.
Les préfixes de cache sont créés dans l’ordre suivant : `tools`, `system`, puis `messages`. Cet ordre forme une hiérarchie où chaque niveau s’appuie sur les précédents.
#### Fonctionnement de la vérification automatique des préfixes
Vous pouvez utiliser un seul point d’arrêt de cache à la fin de votre contenu statique, et le système trouve automatiquement le plus long préfixe qu’une requête antérieure a déjà écrit dans le cache. Comprendre ce fonctionnement vous aide à optimiser votre stratégie de mise en cache.
**Trois principes fondamentaux :**
1. **Les écritures en cache ont lieu uniquement à votre point d’arrêt.** Marquer un bloc avec `cache_control` écrit exactement une entrée de cache : un hachage du préfixe se terminant à ce bloc. Le système n’écrit pas d’entrées pour une position antérieure. Comme le hachage est cumulatif, couvrant tout jusqu’au point d’arrêt inclus, la modification de n’importe quel bloc situé au point d’arrêt ou avant celui-ci produit un hachage différent lors de la requête suivante.
2. **Les lectures du cache remontent en arrière pour trouver les entrées écrites par les requêtes antérieures.** À chaque requête, le système calcule le hachage du préfixe à votre point d’arrêt et recherche une entrée de cache correspondante. S’il n’en existe aucune, il remonte un bloc à la fois, en vérifiant si le hachage du préfixe à chaque position antérieure correspond à quelque chose déjà présent dans le cache. Il recherche des écritures antérieures, et non du contenu stable.
3. **La fenêtre de rétrospection est de 20 blocs.** Le système vérifie au maximum 20 positions pour chaque point d’arrêt, en comptant le point d’arrêt lui-même comme la première. Si le système ne trouve aucune entrée correspondante dans cette fenêtre, la vérification s’arrête (ou reprend à partir du point d’arrêt explicite suivant, s’il y en a un). Sur l’API Claude, une série de blocs `tool_use` consécutifs compte comme une seule position, tout comme une série de blocs `tool_result` consécutifs, de sorte qu’un tour comportant de nombreux appels d’outils parallèles ne repousse pas à lui seul l’entrée de la requête précédente hors de la fenêtre.
**Exemple : rétrospection dans une conversation qui s’allonge**
Vous ajoutez de nouveaux blocs à chaque tour et définissez `cache_control` sur le dernier bloc de chaque requête :
* **Tour 1 :** 10 blocs, point d’arrêt sur le bloc 10. Aucune entrée de cache antérieure n’existe. Le système écrit une entrée au bloc 10.
* **Tour 2 :** 15 blocs, point d’arrêt sur le bloc 15. Le bloc 15 n’a pas d’entrée, le système remonte donc jusqu’au bloc 10 et trouve l’entrée du tour 1. Succès de cache au bloc 10. Le système ne traite à nouveau que les blocs 11 à 15 et écrit une nouvelle entrée au bloc 15.
* **Tour 3 :** 35 blocs, point d’arrêt sur le bloc 35. Le système vérifie 20 positions (blocs 35 à 16) et ne trouve rien. L’entrée du tour 2 au bloc 15 se trouve une position en dehors de la fenêtre, il n’y a donc pas de succès de cache. L’ajout d’un second point d’arrêt au bloc 15 démarre une seconde fenêtre de rétrospection à cet endroit, qui trouve l’entrée du tour 2.
**Erreur courante : point d’arrêt sur un contenu qui change à chaque requête**
Votre prompt comporte un grand contexte système statique (blocs 1 à 5) suivi d’un bloc propre à chaque requête contenant un horodatage et le message de l’utilisateur (bloc 6). Vous définissez `cache_control` sur le bloc 6 :
* **Requête 1 :** Écriture en cache au bloc 6. Le hachage inclut l’horodatage.
* **Requête 2 :** L’horodatage diffère, donc le hachage du préfixe au bloc 6 diffère. La rétrospection parcourt les blocs 5, 4, 3, 2 et 1, mais le système n’a jamais écrit d’entrée à aucune de ces positions. Aucun succès de cache. Vous payez une nouvelle écriture en cache à chaque requête et n’obtenez jamais de lecture.
La rétrospection ne trouve pas le contenu stable situé derrière votre point d’arrêt pour le mettre en cache. Elle trouve les entrées que des requêtes antérieures ont déjà écrites, et les écritures n’ont lieu qu’aux points d’arrêt. Déplacez `cache_control` sur le bloc 5, le dernier bloc qui reste identique d’une requête à l’autre, et chaque requête suivante lira le préfixe mis en cache. La [mise en cache automatique](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#automatic-caching) présente le même problème : elle place le point d’arrêt sur le dernier bloc pouvant être mis en cache, qui dans cette structure est celui qui change à chaque requête ; utilisez donc plutôt un point d’arrêt explicite sur le bloc 5.
**À retenir :** Placez `cache_control` sur le dernier bloc dont le préfixe est identique pour toutes les requêtes devant partager un cache. Dans une conversation qui s’allonge, le dernier bloc convient tant que chaque tour ajoute moins de 20 blocs : le contenu antérieur ne change jamais, donc la rétrospection de la requête suivante trouve l’écriture précédente. Pour un prompt avec un suffixe variable (horodatages, contexte propre à chaque requête, message entrant), placez le point d’arrêt à la fin du préfixe statique, et non sur le bloc variable.
#### Quand utiliser plusieurs points d’arrêt
Vous pouvez définir jusqu’à 4 points d’arrêt 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 un meilleur contrôle de ce qui est mis en cache
* Garantir un succès de cache lorsqu’une conversation qui s’allonge repousse votre point d’arrêt de 20 blocs ou plus au-delà de la dernière écriture en cache
**Limitation importante :** La rétrospection ne peut trouver que les entrées que des requêtes antérieures ont déjà écrites. Si une conversation qui s’allonge repousse votre point d’arrêt de 20 blocs ou plus au-delà de la dernière écriture, la fenêtre de rétrospection la manque. Ajoutez dès le départ un second point d’arrêt plus proche de cette position afin qu’une écriture s’y accumule avant que vous en ayez besoin.
### 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 :
* **Les écritures en cache :** Lorsque du nouveau contenu est écrit dans le cache (25 pour cent de plus que les tokens d’entrée de base pour un TTL de 5 minutes)
* **Les lectures du cache :** Lorsque du contenu mis en cache est utilisé (10 pour cent du prix de base des tokens d’entrée, avec des [exceptions par modèle](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#pricing))
* **Les tokens d’entrée ordinaires :** Pour tout contenu non mis en cache
L’ajout de points d’arrêt `cache_control` supplémentaires n’augmente pas vos coûts ; vous payez toujours le même montant en fonction du contenu effectivement mis en cache et lu. Les points d’arrêt vous permettent de contrôler quelles sections peuvent être mises en cache indépendamment.
***
## Stratégies et considérations de mise en cache
### Limitations du cache
Sur l’API Claude, [Claude Platform on AWS](https://platform.claude.com/docs/fr/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/fr/build-with-claude/claude-models-on-google-cloud/google-managed) et [Microsoft Foundry](https://platform.claude.com/docs/fr/build-with-claude/claude-in-microsoft-foundry), la longueur minimale de prompt pouvant être mise en cache est de :
* 512 tokens pour Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/fr/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/fr/models/mythos-5-1/overview), Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/fr/models/mythos-5/overview) et Claude Haiku 5.5
* 2 048 tokens pour [Claude Mythos Preview](https://anthropic.com/glasswing) et Claude Opus 4.7
* 4 096 tokens pour Claude Opus 4.6 et Claude Opus 4.5
* 1 024 tokens pour Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 ([déprécié](https://platform.claude.com/docs/fr/about-claude/model-deprecations)), Claude Opus 4.1 ([retiré, sauf sur Claude Models on Google Cloud (Google managed) et Bedrock](https://platform.claude.com/docs/fr/about-claude/model-deprecations)), Claude Opus 4 ([retiré, sauf sur Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/fr/about-claude/model-deprecations)) et Claude Sonnet 4 ([retiré, sauf sur Claude Models on Google Cloud (Google managed) et Bedrock](https://platform.claude.com/docs/fr/about-claude/model-deprecations))
* 4 096 tokens pour Claude Haiku 4.5
Ces minimums s’appliquent sur toutes les plateformes où chaque modèle est disponible.
Les prompts plus courts ne peuvent pas être mis en cache, même s’ils sont marqués avec `cache_control`. Toute demande de mise en cache de moins de ce nombre de tokens est traitée sans mise en cache, et aucune erreur n’est renvoyée. Pour vérifier si un prompt a été mis en cache, consultez les [champs d’utilisation de la réponse](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#tracking-cache-performance) : si `cache_creation_input_tokens` et `cache_read_input_tokens` valent tous deux 0, le prompt n’a pas été mis en cache (probablement parce qu’il n’atteignait pas la longueur minimale requise).
Si votre prompt est juste en dessous du minimum pour votre modèle et votre plateforme, il est souvent intéressant d’étendre le contenu mis en cache pour atteindre le seuil. Les lectures du cache coûtent nettement moins cher que les tokens d’entrée non mis en cache ; atteindre le minimum peut donc réduire les coûts pour les prompts fréquemment réutilisés.
[Bedrock](https://platform.claude.com/docs/fr/build-with-claude/claude-in-amazon-bedrock) est une plateforme exploitée par AWS. Sur Bedrock, consultez la [documentation de Bedrock sur la mise en cache des prompts](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) pour connaître les minimums par modèle, le comportement en cas d’échec et les noms des champs d’utilisation applicables.
Pour les requêtes simultanées, notez qu’une entrée de cache ne devient disponible qu’après le début de la première réponse. Si vous avez besoin de succès de cache pour des requêtes parallèles, attendez la première réponse avant d’envoyer les requêtes suivantes.
Actuellement, `ephemeral` est le seul type de cache pris en charge, avec une durée de vie par défaut de 5 minutes.
### Ce qui peut être mis en cache
La plupart des blocs de la requête peuvent être mis en cache. Cela comprend :
* Les outils : définitions d’outils dans le tableau `tools`
* Les messages système : blocs de contenu dans le tableau `system`
* Les messages texte : blocs de contenu dans le tableau `messages.content`, pour les tours de l’utilisateur comme de l’assistant
* Les images et documents : blocs de contenu dans le tableau `messages.content`, dans les tours de l’utilisateur
* L’utilisation d’outils et les résultats d’outils : blocs de contenu dans le tableau `messages.content`, dans les tours de l’utilisateur comme de l’assistant
Chacun de ces éléments peut être mis en cache, soit automatiquement, soit en le marquant avec `cache_control`.
### Ce qui ne peut pas être mis en cache
Bien que la plupart des blocs de requête puissent être mis en cache, il existe quelques exceptions :
* Les blocs de réflexion ne peuvent pas être mis en cache directement avec `cache_control`. Cependant, les blocs de réflexion PEUVENT être mis en cache avec d’autres contenus lorsqu’ils apparaissent dans des tours précédents de l’assistant. Lorsqu’ils sont mis en cache de cette manière, ils SONT comptabilisés comme tokens d’entrée lorsqu’ils sont lus depuis le cache.
* Les sous-blocs de contenu (tels que les [citations](https://platform.claude.com/docs/fr/build-with-claude/citations)) ne peuvent pas eux-mêmes être mis en cache directement. Mettez plutôt en cache le bloc de niveau supérieur.
Dans le cas des citations, les blocs de contenu de document de niveau supérieur qui servent de matériau source pour les citations peuvent être mis en cache. Cela vous permet d’utiliser efficacement la mise en cache des prompts avec les citations en mettant en cache les documents auxquels les citations font référence.
* 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 tout ou partie du cache.
Comme décrit dans [Structurer votre prompt](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#structuring-your-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 indique 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 change | Cache des outils | Cache système | Cache des messages | Impact |
| ---------------------------------------------------------------------- | ---------------- | --------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Définitions d’outils** | ✘ | ✘ | ✘ | La modification des définitions d’outils (noms, descriptions, paramètres) invalide l’ensemble du cache |
| **Activation de la recherche web** | ✓ | ✘ | ✘ | L’activation/désactivation de la recherche web modifie l’invite système |
| **Activation des citations** | ✓ | ✘ | ✘ | L’activation/désactivation des citations modifie l’invite système |
| **Paramètre de vitesse** | ✓ | ✘ | ✘ | Le passage entre [`speed: "fast"` et la vitesse standard](https://platform.claude.com/docs/fr/build-with-claude/fast-mode) invalide les caches système et des messages |
| **Choix d’outil** | ✓ | ✓ | ✘ | Les modifications du paramètre `tool_choice` n’affectent que les blocs de messages |
| **Images** | ✓ | ✓ | ✘ | L’ajout/la suppression d’images n’importe où dans le prompt affecte les blocs de messages |
| **Paramètres de réflexion** | Selon le modèle | Selon le modèle | ✘ | La configuration de la réflexion (le mode, et `budget_tokens` en mode étendu) est intégrée au prompt ; la modifier invalide donc toujours les blocs de messages ; les caches des outils et système sont également invalidés sur les modèles qui intègrent la configuration avant ceux-ci. Consultez [Réflexion et mise en cache des prompts](https://platform.claude.com/docs/fr/build-with-claude/thinking#thinking-and-prompt-caching). |
| **Paramètre d’effort** | Selon le modèle | Selon le modèle | ✘ | La modification de la valeur [`output_config.effort`](https://platform.claude.com/docs/fr/build-with-claude/effort) invalide toujours les blocs de messages, avec le même effet dépendant du modèle sur les caches des outils et système que les paramètres de réflexion. Définir explicitement l’effort à la valeur par défaut du modèle équivaut à l’omettre et n’invalide rien. Sur les modèles qui prennent en charge l’[effort par message](https://platform.claude.com/docs/fr/build-with-claude/effort#change-effort-mid-conversation-beta), un changement d’effort transmis dans un message `role: "system"` à l’intérieur de `messages` laisse le préfixe mis en cache intact. |
| **Résultats autres que d’outils transmis aux requêtes avec réflexion** | ✓ | ✓ | Selon le modèle | Sur Opus 4.5+, Sonnet 4.6+ et Haiku 5.5, les blocs de réflexion sont conservés par défaut, le cache reste donc valide (✓). Sur les modèles Opus/Sonnet antérieurs et les modèles Haiku jusqu’à Claude Haiku 4.5, tous les blocs de réflexion précédemment mis en cache sont retirés du contexte, et tous les messages qui suivent ces blocs de réflexion sont supprimés du cache (✘). Pour plus de détails, consultez [Mise en cache avec les blocs de réflexion](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#caching-with-thinking-blocks). |
| **Blocs de réflexion supprimés** | ✓ | ✓ | ✘ | Lorsque l’API supprime un bloc de réflexion qui n’est pas [conservé](https://platform.claude.com/docs/fr/build-with-claude/thinking#preserved-thinking) sur cette requête, le préfixe mis en cache change à partir de la position de ce bloc sur cette requête. Les blocs que le modèle destinataire peut lire, renvoyés sans modification, conservent le cache intact. |
Sur les modèles qui prennent en charge les [modifications d’outils en cours de conversation](https://platform.claude.com/docs/fr/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), l’en-tête bêta `inline-tools-2026-09-15` vous permet d’ajouter un outil, ou de modifier la définition d’un outil, en cours de conversation sans modifier `tools`. Envoyez la définition dans un bloc `tool_addition` dans un message système en cours de conversation et laissez `tools` exactement tel que vous l’avez envoyé la première fois. Le préfixe mis en cache correspond toujours, de sorte que seul le message ajouté est traité comme une nouvelle entrée. La seule exception est un tableau `tools` ne contenant aucun outil non différé, où le premier outil défini de cette manière coûte un échec de cache complet sur cette requête. Consultez [Définir des outils dans un message](https://platform.claude.com/docs/fr/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta).
Sur Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/fr/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/fr/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/fr/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5 et Claude Haiku 5.5, vous pouvez ajouter une nouvelle instruction système en cours de conversation sans invalider les caches système ou des messages. Ajoutez un message `{"role": "system"}` à `messages` au lieu de modifier le champ `system` de niveau supérieur, afin que le préfixe mis en cache reste inchangé. Cette fonctionnalité n’est pas disponible sur Claude Sonnet 5. Utilisez plutôt le champ `system` de niveau supérieur. Consultez [Messages système et changements d’outils en cours de conversation](https://platform.claude.com/docs/fr/build-with-claude/mid-conversation-system-messages).
### Suivi des performances du cache
Surveillez les performances du cache à l’aide de ces champs de réponse de l’API, dans `usage` de la réponse (ou dans l’événement `message_start` en cas de [streaming](https://platform.claude.com/docs/fr/build-with-claude/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 un cache ni utilisés pour en créer un (c’est-à-dire les tokens après le dernier point d’arrêt de cache)
**Comprendre la répartition des tokens**
Le champ `input_tokens` représente uniquement les tokens qui viennent **après le dernier point d’arrêt de cache** dans votre requête, et non l’ensemble des tokens d’entrée que vous avez envoyés.
Pour calculer le total des tokens d’entrée :
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
**Explication spatiale :**
* `cache_read_input_tokens` = tokens avant le point d’arrêt déjà mis en cache (lectures)
* `cache_creation_input_tokens` = tokens avant le point d’arrêt en cours de mise en cache (écritures)
* `input_tokens` = tokens après votre dernier point d’arrêt (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 d’arrêt de cache) :
* `cache_read_input_tokens` : 100 000
* `cache_creation_input_tokens` : 0
* `input_tokens` : 50
* **Total des tokens d’entrée traités :** 100 050 tokens
Ceci est important pour comprendre à la fois les coûts et les limites de débit, car `input_tokens` est généralement bien inférieur à votre entrée totale lorsque vous utilisez efficacement la mise en cache.
### Mise en cache avec les blocs de réflexion
Lorsque vous utilisez la [réflexion](https://platform.claude.com/docs/fr/build-with-claude/thinking) avec la mise en cache des prompts, les blocs de réflexion ont un comportement particulier :
**Mise en cache automatique avec d’autres contenus :** Bien que les blocs de réflexion ne puissent pas être explicitement marqués avec `cache_control`, ils sont mis en cache dans le cadre du contenu de la requête lorsque vous effectuez des appels API ultérieurs avec des résultats d’outils. Cela se produit couramment lors de l’utilisation d’outils, lorsque vous renvoyez les blocs de réflexion pour poursuivre la conversation.
**Comptabilisation des tokens d’entrée :** Lorsque les blocs de réflexion sont lus depuis le cache, ils sont comptabilisés comme tokens d’entrée dans vos métriques d’utilisation. Ceci est important pour le calcul des coûts et la budgétisation des tokens.
**Schémas d’invalidation du cache :**
* Le cache reste valide lorsque seuls des résultats d’outils sont fournis comme messages utilisateur.
* Sur Opus 4.5+, Sonnet 4.6+ et Haiku 5.5, les blocs de réflexion sont conservés par défaut même lorsque du contenu utilisateur autre que des résultats d’outils est ajouté, le cache reste donc valide.
* Sur les modèles Opus/Sonnet antérieurs et les modèles Haiku jusqu’à Claude Haiku 4.5, le cache est invalidé lorsque du contenu utilisateur autre que des résultats d’outils est ajouté, ce qui entraîne le retrait de tous les blocs de réflexion précédents du contexte.
* Ce comportement de mise en cache se produit même sans marqueurs `cache_control` explicites.
Pour plus de détails sur l’invalidation du cache, consultez [Ce qui invalide le cache](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#what-invalidates-the-cache).
**Exemple avec utilisation d’outils :**
```text wrap
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]
# Depending on the model, this non-tool-result user block either keeps prior thinking blocks or strips them (see the next paragraph)
```
Sur les modèles Opus/Sonnet antérieurs et les modèles Haiku jusqu’à Claude Haiku 4.5, tous les blocs de réflexion précédents sont retirés du contexte à ce stade. Sur Opus 4.5+, Sonnet 4.6+ et Haiku 5.5, les blocs de réflexion antérieurs sont conservés par défaut et restent partie intégrante du préfixe mis en cache.
Pour des informations plus détaillées, consultez [Réflexion et mise en cache des prompts](https://platform.claude.com/docs/fr/build-with-claude/thinking#thinking-and-prompt-caching).
### Stockage et partage du cache
La mise en cache des prompts utilise une isolation au niveau de l’[espace de travail](https://platform.claude.com/docs/fr/manage-claude/workspaces). Les caches sont isolés par espace de travail, garantissant la séparation des données entre les espaces de travail d’une même organisation. Cela s’applique à l’API Claude, à Claude Platform on AWS et à Microsoft Foundry ; Claude Models on Google Cloud (Google managed) et Bedrock conservent une isolation du cache au niveau de l’organisation. Si vous utilisez plusieurs espaces de travail, revoyez votre stratégie de mise en cache pour tenir compte de cette différence.
* **Isolation des organisations et des espaces de travail :** Les caches sont isolés entre les organisations. Des organisations différentes ne partagent jamais de caches, même si elles utilisent des prompts identiques. Les caches sont également isolés par espace de travail au sein d’une organisation sur l’API Claude, Claude Platform on AWS et Microsoft Foundry ; Claude Models on Google Cloud (Google managed) et Bedrock utilisent uniquement une isolation au niveau de l’organisation.
* **Correspondance exacte :** Les succès de cache nécessitent des segments de prompt identiques à 100 %, y compris tout le texte et toutes les images jusqu’au bloc marqué avec le contrôle de cache inclus.
* **Génération des tokens de sortie :** La mise en cache des prompts n’a aucun effet sur la génération des tokens de sortie. La réponse que vous recevez est identique à celle que vous obtiendriez sans la mise en cache des prompts.
### Bonnes pratiques pour une mise en cache efficace
Pour optimiser les performances de la mise en cache des prompts :
* Commencez par la [mise en cache automatique](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#automatic-caching) pour les conversations multi-tours. Elle gère automatiquement les points d’arrêt.
* Utilisez des [points d’arrêt explicites au niveau des blocs](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#explicit-cache-breakpoints) lorsque vous devez mettre en cache différentes sections ayant 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 d’arrêt de cache de manière stratégique pour séparer les différentes sections de préfixe pouvant être mises en cache.
* Placez le point d’arrêt sur le dernier bloc qui reste identique d’une requête à l’autre. Pour un prompt avec un préfixe statique et un suffixe variable (horodatages, contexte propre à chaque requête, message entrant), il s’agit de la fin du préfixe, et non du bloc variable.
* Analysez régulièrement les taux de succès de cache et ajustez votre stratégie si nécessaire.
### Optimisation pour différents cas d’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, en particulier celles comportant de longues instructions ou des documents téléversés.
* Assistants de programmation : améliorez l’autocomplétion et les questions-réponses sur la base de code en conservant les sections pertinentes ou une version résumée de la base de code dans le prompt.
* Traitement de documents volumineux : intégrez du matériel long complet, y compris des images, dans votre prompt sans augmenter la latence de réponse.
* Ensembles d’instructions détaillés : partagez des listes étendues d’instructions, de procédures et d’exemples pour affiner les réponses de Claude. Les développeurs incluent souvent un ou deux exemples dans le prompt, mais avec la mise en cache des prompts, vous pouvez obtenir des performances encore meilleures en incluant plus de 20 exemples variés de réponses de haute qualité.
* Utilisation d’outils agentique : améliorez les performances dans 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.
* Livres, articles, documentation, transcriptions de podcasts et autres contenus longs : rendez n’importe quelle base de connaissances interactive en intégrant le ou les documents complets dans le prompt et en permettant aux utilisateurs de lui poser des questions.
### Résolution des problèmes courants
En cas de comportement inattendu :
Les [diagnostics de cache](https://platform.claude.com/docs/fr/build-with-claude/cache-diagnostics) demandent à l’API de comparer des requêtes consécutives et d’indiquer où le préfixe du prompt a divergé, ce qui prend en charge automatiquement bon nombre des étapes de cette liste.
* Assurez-vous que les sections mises en cache sont identiques d’un appel à l’autre. Pour les points d’arrêt explicites, vérifiez que les marqueurs `cache_control` se trouvent aux mêmes emplacements.
* Vérifiez que les appels sont effectués pendant la durée de vie du cache (5 minutes par défaut).
* Vérifiez que `tool_choice`, l’utilisation d’images, la configuration de la réflexion et `output_config.effort` restent cohérents entre les appels.
* Validez que vous mettez en cache au moins le nombre minimal de tokens pour votre modèle et votre plateforme (consultez [Limitations du cache](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#cache-limitations)).
* Confirmez que votre point d’arrêt se trouve sur un bloc qui reste identique d’une requête à l’autre. Les écritures en cache n’ont lieu qu’au point d’arrêt, et si ce bloc change (horodatages, contexte propre à chaque requête, message entrant), le hachage du préfixe ne correspond jamais. La rétrospection ne trouve pas le contenu stable situé derrière le point d’arrêt ; elle ne trouve que les entrées que des requêtes antérieures ont écrites à leurs propres points d’arrêt.
* Vérifiez que les clés de vos blocs de contenu `tool_use` ont un ordre stable, car certains langages (par exemple Swift, Go) rendent l’ordre des clés aléatoire lors de la conversion JSON, ce qui casse les caches.
* Utilisez les [diagnostics de cache](https://platform.claude.com/docs/fr/build-with-claude/cache-diagnostics) pour demander à l’API de comparer des requêtes consécutives et d’indiquer quelle partie du prompt a divergé.
Les modifications de `tool_choice` ou la présence/absence d’images n’importe où dans le prompt invalident le cache, ce qui nécessite la création d’une nouvelle entrée de cache. Pour plus de détails sur l’invalidation du cache, consultez [Ce qui invalide le cache](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#what-invalidates-the-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 [moyennant un coût supplémentaire](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#pricing).
La durée de cache d’1 heure est disponible sur l’API Claude, [Amazon Bedrock](https://platform.claude.com/docs/fr/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (Opus 4.6 et versions antérieures)](https://platform.claude.com/docs/fr/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/fr/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/fr/build-with-claude/claude-models-on-google-cloud/google-managed) et [Microsoft Foundry](https://platform.claude.com/docs/fr/build-with-claude/claude-in-microsoft-foundry).
Pour utiliser le cache étendu, incluez `ttl` dans la définition de `cache_control` comme ceci :
```json
"cache_control": {
"type": "ephemeral",
"ttl": "1h"
}
```
La réponse inclut des informations détaillées sur le cache, comme suit :
```json Output
{
"usage": {
"input_tokens": 2048,
"cache_read_input_tokens": 1800,
"cache_creation_input_tokens": 248,
"output_tokens": 503,
"cache_creation": {
"ephemeral_5m_input_tokens": 148,
"ephemeral_1h_input_tokens": 100
}
}
}
```
Le champ `cache_creation_input_tokens` est égal à la somme des valeurs de l’objet `cache_creation`.
Si vous constatez des écritures `ephemeral_5m_input_tokens` que vous n’avez pas demandées lors de l’utilisation d’outils serveur tels que la recherche web, consultez [Les résultats des outils serveur sont mis en cache automatiquement](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-use-with-prompt-caching#server-tool-results-are-cached-automatically).
### Quand utiliser le cache d’1 heure
Si vous utilisez un prompt à une cadence régulière (par exemple, une invite système que vous envoyez plus fréquemment que toutes les 5 minutes), continuez à utiliser le cache de 5 minutes, car celui-ci continue d’être rafraîchi sans frais supplémentaires.
Le cache d’1 heure est le plus adapté aux 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 prend plus de 5 minutes, ou lorsque vous stockez une longue conversation de chat avec un utilisateur et que vous vous attendez généralement à ce que cet utilisateur ne réponde pas dans les 5 prochaines minutes.
* Lorsque la latence est importante et que vos prompts de suivi peuvent être envoyés au-delà de 5 minutes.
* Lorsque vous souhaitez améliorer l’utilisation de votre limite de débit, car les succès de cache ne sont pas décomptés de votre limite de débit.
Les caches de 5 minutes et d’1 heure se comportent de la même manière en ce qui concerne la latence. Vous constatez généralement une amélioration du délai avant le premier token pour les documents longs.
### Combiner différentes TTL
Vous pouvez utiliser des 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 ayant une TTL plus longue doivent apparaître avant celles ayant une TTL plus courte (c’est-à-dire qu’une entrée de cache de 1 heure doit apparaître avant toute entrée de cache de 5 minutes).
Lorsque vous combinez des TTL, l’API Claude détermine trois positions de facturation dans votre prompt :
1. Position `A` : le nombre de tokens au niveau du dernier « cache hit » (succès de cache) dans votre prompt (ou 0 s’il n’y a aucun succès).
* Un succès de cache sur une entrée mise en cache avec une TTL de 5 minutes n’est pas retenu si un bloc `cache_control` dont la TTL est de 1 heure, situé plus loin que cette entrée dans le prompt, est un échec de cache.
* Une requête qui lit une entrée mise en cache avec une TTL de 5 minutes fait redémarrer la durée de vie de 5 minutes de cette entrée, même si la requête définit désormais `"ttl": "1h"`.
2. Position `B` : le nombre de tokens au niveau du dernier bloc `cache_control` dont la TTL est de 1 heure, situé plus loin que `A` dans le prompt (ou égal à `A` s’il n’en existe aucun).
3. Position `C` : le nombre de tokens au niveau du dernier bloc `cache_control`.
Si `B` ou `C` est supérieur à `A`, il s’agit nécessairement d’un « cache miss » (échec de cache).
Vous êtes facturé pour :
1. Les tokens de lecture du cache pour `A`.
2. Les tokens d’écriture du cache de 1 heure pour `(B - A)`.
3. Les tokens d’écriture du cache de 5 minutes pour `(C - B)`.
Voici trois exemples de requêtes, chacune ayant des succès et des échecs de cache différents. Chacune a un prix calculé différent, indiqué dans les encadrés.
***
## Préchauffage du cache
Le préchauffage du cache vous permet de charger votre invite système ou vos définitions d’outils dans le cache des prompts avant qu’un utilisateur ne déclenche une véritable requête. Cela peut réduire la pénalité de latence liée à l’échec de cache lors de la première interaction de l’utilisateur, diminuant ainsi le « time-to-first-token » (délai jusqu’au premier token), ou TTFT, pour les applications sensibles à la latence.
### Fonctionnement
Définissez `max_tokens: 0` dans votre requête. L’API lit votre prompt dans le modèle et écrit le cache à chaque point d’arrêt `cache_control`, puis renvoie immédiatement une réponse sans générer de sortie. La réponse contient un tableau `content` vide, `stop_reason: "max_tokens"` et un bloc `usage` entièrement renseigné.
Placez le point d’arrêt `cache_control` sur le dernier bloc partagé avec la requête suivante (généralement votre invite système ou vos définitions d’outils), et non sur le message utilisateur de substitution. Sinon, l’entrée de cache est associée au message de substitution et la requête suivante ne l’atteindra pas. Utilisez également la même configuration de réflexion et le même `output_config.effort` que vos requêtes suivantes : ces valeurs sont intégrées au prompt (voir [Ce qui invalide le cache](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#what-invalidates-the-cache)), de sorte qu’un préchauffage avec une configuration différente peut écrire une entrée que votre trafic réel n’atteindra jamais. Cela implique d’utiliser un [point d’arrêt de cache explicite](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#explicit-cache-breakpoints) plutôt que la [mise en cache automatique](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#automatic-caching), car la mise en cache automatique place le point d’arrêt sur le dernier bloc, qui est ici le message de substitution. Le message utilisateur de substitution peut être n’importe quelle chaîne comportant un contenu autre que des espaces (les exemples ici utilisent `"warmup"`) ; son contenu est lu par le modèle mais ne reçoit jamais de réponse.
Une requête de préchauffage entraîne des frais d’**écriture dans le cache** si le préfixe n’est pas déjà en cache, comme toute autre requête. Vérifiez `usage.cache_creation_input_tokens` dans la réponse pour confirmer qu’une écriture a eu lieu. Aucun token de sortie n’est facturé.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 0,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "warmup"}]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 0
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: warmup
YAML
```
```python Python
client = anthropic.Anthropic()
# Exécutez ceci avant l'arrivée des utilisateurs pour préchauffer le cache partagé de l'invite système.
prewarm = client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=[
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
],
messages=[{"role": "user", "content": "warmup"}],
)
print(prewarm.stop_reason) # "max_tokens"
print(prewarm.content) # []
print(prewarm.usage)
```
```typescript TypeScript
const client = new Anthropic();
// Lancez ceci avant l'arrivée des utilisateurs pour préchauffer le cache de l'invite système partagée.
const prewarm = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 0,
system: [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: { type: "ephemeral" }
}
],
messages: [{ role: "user", content: "warmup" }]
});
console.log(prewarm.stop_reason); // "max_tokens"
console.log(prewarm.content); // []
console.log(prewarm.usage);
```
```csharp C#
AnthropicClient client = new();
var prewarm = await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 0,
System = new(
[
new TextBlockParam
{
Text = "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl = new(),
},
]
),
Messages = [new UserMessageParam { Content = "warmup" }],
}
);
Console.WriteLine(prewarm.StopReason?.Raw()); // "max_tokens"
Console.WriteLine(prewarm.Content.Count); // 0
Console.WriteLine(prewarm.Usage);
```
```go Go
client := anthropic.NewClient()
prewarm, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 0,
System: []anthropic.TextBlockParam{
{
Text: "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
},
})
if err != nil {
panic(err)
}
fmt.Println(prewarm.StopReason) // "max_tokens"
fmt.Println(prewarm.Content) // []
fmt.Println(prewarm.Usage.RawJSON())
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
Message prewarm = client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(0)
.systemOfTextBlockParams(List.of(TextBlockParam.builder()
.text("You are an expert software engineer with deep knowledge of distributed systems...")
.cacheControl(CacheControlEphemeral.builder().build())
.build()))
.addUserMessage("warmup")
.build());
IO.println(prewarm.stopReason()); // Optional[max_tokens]
IO.println(prewarm.content()); // []
IO.println(prewarm.usage());
```
```php PHP
$client = new Client();
$prewarm = $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 0,
system: [
[
'type' => 'text',
'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
'cache_control' => ['type' => 'ephemeral'],
],
],
messages: [['role' => 'user', 'content' => 'warmup']],
);
echo $prewarm->stopReason, PHP_EOL; // "max_tokens"
echo json_encode($prewarm->content), PHP_EOL; // []
echo json_encode($prewarm->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
prewarm = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 0,
system_: [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: {type: "ephemeral"}
}
],
messages: [{role: "user", content: "warmup"}]
)
puts prewarm.stop_reason # :max_tokens
puts prewarm.content # []
puts prewarm.usage
```
L’API renvoie un tableau `content` vide :
```json Output
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [],
"model": "claude-opus-5-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 8,
"cache_creation_input_tokens": 5120,
"cache_read_input_tokens": 0,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"iterations": [
{
"input_tokens": 8,
"output_tokens": 0,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 5120,
"cache_creation": {
"ephemeral_5m_input_tokens": 5120,
"ephemeral_1h_input_tokens": 0
},
"type": "message"
}
],
"output_tokens": 0,
"service_tier": "standard",
"inference_geo": "global"
}
}
```
### Modèle d’utilisation typique
Effectuez une requête de préchauffage au démarrage de votre application (ou à intervalles planifiés), puis envoyez les véritables requêtes des utilisateurs une fois le préchauffage terminé :
```bash cURL
# Préchauffez le cache au démarrage de l'application ou à intervalle planifié.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 0,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "warmup"}]
}'
# Plus tard, lorsque l'utilisateur envoie un message, le préfixe de l'invite système est déjà en cache.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "How do I implement a binary search tree?"}]
}'
```
```bash CLI
# Préchauffez le cache au démarrage de l'application ou à intervalle régulier planifié.
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 0
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: warmup
YAML
# Plus tard, lorsque l'utilisateur envoie un message, le préfixe de l'invite système est déjà en cache.
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
system:
- type: text
text: >-
You are an expert software engineer with deep knowledge of
distributed systems...
cache_control:
type: ephemeral
messages:
- role: user
content: How do I implement a binary search tree?
YAML
```
```python Python
client = anthropic.Anthropic()
SYSTEM_PROMPT = [
{
"type": "text",
"text": "You are an expert software engineer with deep knowledge of distributed systems...",
"cache_control": {"type": "ephemeral"},
}
]
def prewarm_cache() -> None:
"""Call this at application startup or on a scheduled interval."""
client.messages.create(
model="claude-opus-5-5",
max_tokens=0,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": "warmup"}],
)
def respond(user_message: str) -> anthropic.types.Message:
"""The real user request; benefits from a warm cache."""
return client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=SYSTEM_PROMPT,
messages=[{"role": "user", "content": user_message}],
)
# Préchauffez le cache avant l'arrivée de tout trafic utilisateur.
prewarm_cache()
# Plus tard, lorsque l'utilisateur envoie un message, le préfixe de l'invite système est déjà en cache.
response = respond("How do I implement a binary search tree?")
for block in response.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
const client = new Anthropic();
const SYSTEM_PROMPT: Anthropic.TextBlockParam[] = [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: { type: "ephemeral" }
}
];
// Appelez ceci au démarrage de l'application ou à intervalle régulier.
async function prewarmCache(): Promise {
await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 0,
system: SYSTEM_PROMPT,
messages: [{ role: "user", content: "warmup" }]
});
}
// La véritable requête de l'utilisateur ; elle bénéficie d'un cache préchauffé.
async function respond(userMessage: string): Promise {
return client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
system: SYSTEM_PROMPT,
messages: [{ role: "user", content: userMessage }]
});
}
// Préchauffez le cache avant l'arrivée de tout trafic utilisateur.
await prewarmCache();
// Plus tard, lorsque l'utilisateur envoie un message, le préfixe de l'invite système est déjà en cache.
const response = await respond("How do I implement a binary search tree?");
const textBlock = response.content.find((block) => block.type === "text");
console.log(textBlock?.text);
```
```csharp C#
AnthropicClient client = new();
List systemPrompt =
[
new TextBlockParam
{
Text = "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl = new(),
},
];
// Appelez ceci au démarrage de l'application ou à intervalle planifié.
async Task PrewarmCache() =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 0,
System = new(systemPrompt),
Messages = [new UserMessageParam { Content = "warmup" }],
}
);
// La véritable requête utilisateur ; elle bénéficie d'un cache préchauffé.
async Task Respond(string userMessage) =>
await client.Messages.Create(
new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new(systemPrompt),
Messages = [new UserMessageParam { Content = userMessage }],
}
);
// Préchauffez le cache avant l'arrivée de tout trafic utilisateur.
await PrewarmCache();
// Plus tard, lorsque l'utilisateur envoie un message, le préfixe de l'invite système est déjà en cache.
var response = await Respond("How do I implement a binary search tree?");
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
Console.WriteLine(textBlock.Text);
}
}
```
```go Go
var client = anthropic.NewClient()
var systemPrompt = []anthropic.TextBlockParam{
{
Text: "You are an expert software engineer with deep knowledge of distributed systems...",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
}
// Appelez ceci au démarrage de l'application ou à intervalle régulier.
func prewarmCache() error {
_, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 0,
System: systemPrompt,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),
},
})
return err
}
// La vraie requête utilisateur ; elle bénéficie d'un cache déjà chaud.
func respond(userMessage string) (*anthropic.Message, error) {
return client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: systemPrompt,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock(userMessage)),
},
})
}
func main() {
// Préchauffez le cache avant l'arrivée de tout trafic utilisateur.
if err := prewarmCache(); err != nil {
log.Fatal(err)
}
// Plus tard, lorsque l'utilisateur envoie un message, le préfixe de l'invite système est déjà en cache.
response, err := respond("How do I implement a binary search tree?")
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
fmt.Println(textBlock.Text)
}
}
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List systemPrompt = List.of(TextBlockParam.builder()
.text("You are an expert software engineer with deep knowledge of distributed systems...")
.cacheControl(CacheControlEphemeral.builder().build())
.build());
// Appelez ceci au démarrage de l'application ou à intervalle planifié.
void prewarmCache() {
client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(0)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage("warmup")
.build());
}
// La vraie requête utilisateur ; elle bénéficie d'un cache préchauffé.
Message respond(String userMessage) {
return client.messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(systemPrompt)
.addUserMessage(userMessage)
.build());
}
void main() {
// Préchauffez le cache avant l'arrivée de tout trafic utilisateur.
prewarmCache();
// Plus tard, quand l'utilisateur envoie un message, le préfixe de l'invite système est déjà en cache.
Message response = respond("How do I implement a binary search tree?");
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
$client = new Client();
$systemPrompt = [
[
'type' => 'text',
'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',
'cache_control' => ['type' => 'ephemeral'],
],
];
// Appelez ceci au démarrage de l'application ou à intervalle planifié.
$prewarmCache = fn () => $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 0,
system: $systemPrompt,
messages: [['role' => 'user', 'content' => 'warmup']],
);
// La vraie requête utilisateur ; elle bénéficie d'un cache déjà chaud.
$respond = fn (string $userMessage) => $client->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
system: $systemPrompt,
messages: [['role' => 'user', 'content' => $userMessage]],
);
// Préchauffez le cache avant l'arrivée de tout trafic utilisateur.
$prewarmCache();
// Plus tard, lorsque l'utilisateur envoie un message, le préfixe de l'invite système est déjà en cache.
$response = $respond('How do I implement a binary search tree?');
foreach ($response->content as $block) {
if ($block instanceof \Anthropic\Messages\TextBlock) {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
SYSTEM_PROMPT = [
{
type: "text",
text: "You are an expert software engineer with deep knowledge of distributed systems...",
cache_control: {type: "ephemeral"}
}
]
# Appelez ceci au démarrage de l'application ou à intervalle planifié.
def prewarm_cache(client)
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 0,
system_: SYSTEM_PROMPT,
messages: [{role: "user", content: "warmup"}]
)
end
# La véritable requête utilisateur ; elle bénéficie d'un cache préchauffé.
def respond(client, user_message)
client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
system_: SYSTEM_PROMPT,
messages: [{role: "user", content: user_message}]
)
end
# Préchauffez le cache avant l'arrivée de tout trafic utilisateur.
prewarm_cache(client)
# Plus tard, lorsque l'utilisateur envoie un message, le préfixe de l'invite système est déjà en cache.
response = respond(client, "How do I implement a binary search tree?")
response.content.each do |block|
puts block.text if block.is_a?(Anthropic::Models::TextBlock)
end
```
Gardez à l’esprit que la TTL du cache s’applique toujours. Pour le cache par défaut de 5 minutes, envoyez une nouvelle requête de préchauffage au moins toutes les 5 minutes pour maintenir le cache chaud. Pour des intervalles plus longs entre les requêtes des utilisateurs, utilisez plutôt la [durée de cache de 1 heure](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#1-hour-cache-duration).
### Limitations
Une requête `max_tokens: 0` est rejetée avec une erreur `invalid_request_error` si l’un des éléments suivants est défini, car chacun implique une sortie qu’un budget de zéro token ne peut pas produire :
* `stream: true`
* [Réflexion étendue](https://platform.claude.com/docs/fr/build-with-claude/extended-thinking) (`thinking.type: "enabled"`)
* [Sorties structurées](https://platform.claude.com/docs/fr/build-with-claude/structured-outputs) (`output_config.format`)
* `tool_choice` de type `{"type": "tool", ...}` ou `{"type": "any"}`
`max_tokens: 0` est également rejeté dans une requête [Message Batches](https://platform.claude.com/docs/fr/build-with-claude/batch-processing). Le préchauffage vise le délai jusqu’au premier token, qui ne s’applique pas au traitement par lots, et une entrée de cache écrite pendant le traitement par lots expirerait probablement avant l’exécution de la requête suivante.
### Remplacer la solution de contournement `max_tokens=1`
Certaines applications envoient des requêtes `max_tokens: 1` pour préchauffer le cache. Privilégiez `max_tokens: 0` lorsque la requête le permet : aucune sortie n’est produite, il n’y a donc aucune réponse d’un seul token à ignorer, aucun token de sortie n’est facturé et l’intention de la requête est sans ambiguïté.
***
## Exemples de mise en cache des prompts
Pour vous aider à démarrer avec la « prompt caching » (mise en cache des prompts), la [recette de mise en cache des prompts](https://platform.claude.com/cookbook/misc-prompt-caching) du Claude Cookbook fournit des exemples détaillés et des bonnes pratiques.
Les extraits de code suivants présentent divers modèles de mise en cache des prompts. Ces exemples montrent comment implémenter la mise en cache dans différents scénarios, pour vous aider à comprendre les applications pratiques de cette fonctionnalité :
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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?"
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-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?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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?",
}
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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?"
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "You are an AI assistant tasked with analyzing legal documents.",
},
new TextBlockParam()
{
Text = "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new UserMessageParam
{
Content = "What are the key terms and conditions in this agreement?"
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "You are an AI assistant tasked with analyzing legal documents.",
},
{
Text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What are the key terms and conditions in this agreement?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.text("You are an AI assistant tasked with analyzing legal documents.")
.build(),
TextBlockParam.builder()
.text(
"Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("What are the key terms and conditions in this agreement?")
.build();
Message message = client.messages().create(params);
IO.println(message.usage());
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => 'What are the key terms and conditions in this agreement?'
]
],
model: Model::CLAUDE_OPUS_5_5,
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']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_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?"
}
]
)
puts message.usage
```
Cet exemple illustre l’utilisation de base de la mise en cache des prompts, en mettant en cache le texte intégral de l’accord juridique comme préfixe tout en laissant l’instruction de l’utilisateur hors cache.
Pour la première requête :
* `input_tokens` : nombre de tokens dans le message utilisateur uniquement
* `cache_creation_input_tokens` : nombre de tokens dans l’ensemble du message système, y compris le document juridique
* `cache_read_input_tokens` : 0 (aucun succès de cache lors de la première requête)
Pour les requêtes suivantes pendant la durée de vie du cache :
* `input_tokens` : nombre de tokens dans le message utilisateur uniquement
* `cache_creation_input_tokens` : 0 (aucune nouvelle création de cache)
* `cache_read_input_tokens` : nombre de tokens dans l’ensemble du message système mis en cache
Les définitions d’outils peuvent être mises en cache en plaçant `cache_control` sur le dernier outil de votre tableau `tools`. Tous les outils définis jusqu’à cet outil inclus sont mis en cache comme un seul préfixe.
```json
{
"model": "claude-opus-5-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" } },
"required": ["location"]
}
},
{
"name": "get_time",
"description": "Get the current time in a given time zone",
"input_schema": {
"type": "object",
"properties": { "timezone": { "type": "string" } },
"required": ["timezone"]
},
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]
}
```
Lors de la première requête, `cache_creation_input_tokens` reflète le nombre de tokens de toutes les définitions d’outils. Lors des requêtes suivantes pendant la durée de vie du cache, ces tokens apparaissent plutôt sous `cache_read_input_tokens`.
Pour plus de détails sur l’interaction entre les définitions d’outils, `defer_loading` et l’invalidation du cache, consultez [Utilisation d’outils avec la mise en cache des prompts](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/tool-use-with-prompt-caching).
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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"}
}
]
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "...long system prompt",
"cache_control": {"type": "ephemeral"},
}
],
messages=[
# ...longue conversation jusqu'ici
{
"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'd 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"},
},
],
},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
system: [
{
type: "text",
text: "...long system prompt",
cache_control: { type: "ephemeral" }
}
],
messages: [
// ...longue conversation jusqu'ici
{
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'd 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" }
}
]
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
Text = "...long system prompt",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new UserMessageParam
{
Content = new List
{
new ContentBlockParam(new TextBlockParam("Hello, can you tell me more about the solar system?")),
},
},
new AssistantMessageParam
{
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?"
},
new UserMessageParam
{
Content = new List
{
new ContentBlockParam(new TextBlockParam("Good to know.")),
new ContentBlockParam(new TextBlockParam()
{
Text = "Tell me more about Mars.",
CacheControl = new CacheControlEphemeral(),
}),
}
}
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "...long system prompt",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, can you tell me more about the solar system?")),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("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?")),
anthropic.NewUserMessage(
anthropic.NewTextBlock("Good to know."),
anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{
Text: "Tell me more about Mars.",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Créer une invite système éphémère
TextBlockParam systemPrompt = TextBlockParam.builder()
.text("...long system prompt")
.cacheControl(CacheControlEphemeral.builder().build())
.build();
// Créer les paramètres du message
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(List.of(systemPrompt))
// Premier message utilisateur (sans contrôle du cache)
.addUserMessage("Hello, can you tell me more about the solar system?")
// Réponse de l'assistant
.addAssistantMessage(
"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?"
)
// Deuxième message utilisateur (avec contrôle du cache)
.addUserMessageOfContentBlockParams(
List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Good to know.")
.build()),
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Tell me more about Mars.")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
)
.build();
Message message = client.messages().create(params);
IO.println(message.usage());
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
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']
]
]
]
],
model: Model::CLAUDE_OPUS_5_5,
system: [
[
'type' => 'text',
'text' => '...long system prompt',
'cache_control' => ['type' => 'ephemeral']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_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" }
}
]
}
]
)
puts message.usage
```
Cet exemple montre comment utiliser la mise en cache des prompts dans une conversation à plusieurs tours.
À chaque tour, le dernier bloc du dernier message est marqué avec `cache_control` afin que la conversation puisse être mise en cache de manière incrémentale. Le système recherche et utilise automatiquement la plus longue séquence de blocs précédemment mise en cache pour les messages suivants. Les blocs qui ont été marqués avec `cache_control` lors d’un tour précédent ne sont pas marqués à nouveau, mais une requête effectuée dans un délai de 5 minutes les lit toujours depuis le cache et rafraîchit leur durée de vie.
Le paramètre `cache_control` est également placé sur le message système. Si le message système est évincé du cache après être resté inutilisé pendant plus de 5 minutes, la requête suivante le réintègre.
Cette approche est utile pour conserver le contexte dans des conversations en cours sans traiter de manière répétée les mêmes informations.
Lorsque tout est correctement configuré, 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 (minimal)
* `cache_creation_input_tokens` : nombre de tokens dans les nouveaux tours de l’assistant et de l’utilisateur
* `cache_read_input_tokens` : nombre de tokens dans la conversation jusqu’au tour précédent
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5-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"}
}
]
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-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.
# Instructions
- Always search for relevant documents before answering
- Provide citations for your sources
- Be objective and accurate in your responses
- If multiple documents contain relevant information, synthesize them
- Acknowledge when information is not available in the knowledge base
cache_control:
type: ephemeral
- type: text
text: |-
# Knowledge Base Context
Here are the relevant documents for this conversation:
## Document 1: Solar System Overview
The solar system consists of the Sun and all objects that orbit it...
## Document 2: Planetary Characteristics
Each planet has unique features. Mercury is the smallest planet...
## Document 3: Mars Exploration
Mars has been a target of exploration for decades...
[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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-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"},
}
],
},
],
)
print(response.usage.model_dump_json())
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-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" }
}
]
}
]
});
console.log(response.usage);
```
```csharp C#
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools =
[
new ToolUnion(new Tool()
{
Name = "search_documents",
Description = "Search through the knowledge base",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Search query" }),
},
Required = ["query"],
},
}),
new ToolUnion(new Tool()
{
Name = "get_document",
Description = "Retrieve a specific document by ID",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["doc_id"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Document ID" }),
},
Required = ["doc_id"],
},
CacheControl = new CacheControlEphemeral(),
}),
],
System = new MessageCreateParamsSystem(new List
{
new TextBlockParam()
{
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",
CacheControl = new CacheControlEphemeral(),
},
new TextBlockParam()
{
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...]",
CacheControl = new CacheControlEphemeral(),
},
}),
Messages =
[
new UserMessageParam { Content = "Can you search for information about Mars rovers?" },
new AssistantMessageParam
{
Content = new List
{
new ContentBlockParam(new ToolUseBlockParam()
{
ID = "tool_1",
Name = "search_documents",
Input = new Dictionary
{
["query"] = JsonSerializer.SerializeToElement("Mars rovers"),
},
}),
},
},
new UserMessageParam
{
Content = new List
{
new ContentBlockParam(new ToolResultBlockParam()
{
ToolUseID = "tool_1",
Content = "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
}),
},
},
new AssistantMessageParam
{
Content = "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",
},
new UserMessageParam
{
Content = new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = "Yes, please tell me about the Perseverance rover specifically.",
CacheControl = new CacheControlEphemeral(),
}),
},
},
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message.Usage);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "search_documents",
Description: anthropic.String("Search through the knowledge base"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"query": map[string]any{
"type": "string",
"description": "Search query",
},
},
Required: []string{"query"},
},
}},
{OfTool: &anthropic.ToolParam{
Name: "get_document",
Description: anthropic.String("Retrieve a specific document by ID"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"doc_id": map[string]any{
"type": "string",
"description": "Document ID",
},
},
Required: []string{"doc_id"},
},
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
},
System: []anthropic.TextBlockParam{
{
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",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
{
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...]",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Can you search for information about Mars rovers?")),
anthropic.NewAssistantMessage(anthropic.NewToolUseBlock(
"tool_1",
map[string]any{"query": "Mars rovers"},
"search_documents",
)),
anthropic.NewUserMessage(anthropic.NewToolResultBlock(
"tool_1",
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
false,
)),
anthropic.NewAssistantMessage(anthropic.NewTextBlock("I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.")),
anthropic.NewUserMessage(anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{
Text: "Yes, please tell me about the Perseverance rover specifically.",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}}),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Usage.RawJSON())
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Schéma de l'outil de recherche
InputSchema searchSchema = InputSchema.builder()
.properties(
JsonValue.from(
Map.of("query", Map.of("type", "string", "description", "Search query"))
)
)
.putAdditionalProperty("required", JsonValue.from(List.of("query")))
.build();
// Schéma de l'outil de récupération de document
InputSchema getDocSchema = InputSchema.builder()
.properties(
JsonValue.from(
Map.of("doc_id", Map.of("type", "string", "description", "Document ID"))
)
)
.putAdditionalProperty("required", JsonValue.from(List.of("doc_id")))
.build();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
// Outils avec contrôle du cache sur le dernier
.addTool(
Tool.builder()
.name("search_documents")
.description("Search through the knowledge base")
.inputSchema(searchSchema)
.build()
)
.addTool(
Tool.builder()
.name("get_document")
.description("Retrieve a specific document by ID")
.inputSchema(getDocSchema)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
// Invites système avec contrôle du cache séparé pour les instructions et le contexte
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.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"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build(),
TextBlockParam.builder()
.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...]"
)
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
// Historique de la conversation
.addUserMessage("Can you search for information about Mars rovers?")
.addAssistantMessageOfContentBlockParams(
List.of(
ContentBlockParam.ofToolUse(
ToolUseBlockParam.builder()
.id("tool_1")
.name("search_documents")
.input(JsonValue.from(Map.of("query", "Mars rovers")))
.build()
)
)
)
.addUserMessageOfContentBlockParams(
List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId("tool_1")
.content(
"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"
)
.build()
)
)
)
.addAssistantMessageOfContentBlockParams(
List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text(
"I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."
)
.build()
)
)
)
.addUserMessageOfContentBlockParams(
List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("Yes, please tell me about the Perseverance rover specifically.")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
)
.build();
Message message = client.messages().create(params);
IO.println(message.usage());
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
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']
]
]
]
],
model: Model::CLAUDE_OPUS_5_5,
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']
]
],
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']
]
],
);
echo json_encode($message->usage), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_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" }
}
]
}
]
)
puts message.usage
```
Cet exemple complet 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 de l’invite système sont mises en cache séparément. Ces instructions changent rarement d’une requête à l’autre.
3. **Cache du contexte RAG** (point d’arrêt de cache 3) : les documents de la base de connaissances sont mis en cache indépendamment, ce qui vous permet 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) : le dernier message utilisateur est marqué avec `cache_control` pour permettre la mise en cache incrémentale de la conversation au fur et à mesure de sa progression.
Cette approche offre une flexibilité maximale :
* Si vous ajoutez un nouveau tour à la conversation sans modifier le contenu antérieur, les quatre segments de cache sont réutilisés.
* Si vous mettez à jour les documents RAG tout en conservant les mêmes outils et instructions, les deux premiers segments de cache sont réutilisés.
* Si vous modifiez la conversation tout en conservant les mêmes outils, instructions et documents, les trois premiers segments sont réutilisés.
* Les modifications à n’importe quel point d’arrêt invalident ce segment et tout ce qui suit, tandis que les segments mis en cache antérieurs restent valides.
Pour la première requête :
* `input_tokens` : minimal (tokens après le dernier point d’arrêt de cache, proche de 0 dans cet exemple)
* `cache_creation_input_tokens` : tokens de tous les segments mis en cache (outils + instructions + documents RAG + historique de conversation)
* `cache_read_input_tokens` : 0 (aucun succès de cache)
Pour les requêtes suivantes ne comportant qu’un nouveau message utilisateur (et avec le quatrième point d’arrêt déplacé vers ce nouveau dernier message, comme dans l’exemple) :
* `input_tokens` : minimal (tokens après le dernier point d’arrêt de cache, proche de 0 dans cet exemple)
* `cache_creation_input_tokens` : tokens du nouveau message utilisateur et du tour précédent de l’assistant (le nouveau segment de conversation mis en cache)
* `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 des contextes documentaires volumineux
* Les systèmes d’agents qui utilisent plusieurs outils
* Les conversations de longue durée qui doivent conserver le contexte
* Les applications qui doivent optimiser indépendamment différentes parties du prompt
## Conservation des données
La mise en cache des prompts (automatique comme explicite) est éligible à la ZDR. Anthropic ne stocke pas le texte brut de vos prompts ni les réponses de Claude.
Les représentations du cache KV (clé-valeur) et les hachages cryptographiques du contenu mis en cache sont conservés uniquement en mémoire et ne sont pas stockés au repos. Les entrées mises en cache ont une durée de vie minimale de 5 minutes (standard) ou de 1 heure (étendue), après quoi elles sont supprimées rapidement, mais pas immédiatement. Les entrées de cache sont isolées entre les organisations et, sur l’API Claude, Claude Platform on AWS et Microsoft Foundry, entre les espaces de travail d’une même organisation.
***
## FAQ
**Dans la plupart des cas, un seul point d’arrêt de cache à la fin de votre contenu statique suffit.** Les écritures dans le cache ont lieu uniquement au niveau du bloc que vous marquez. Placez-le sur le dernier bloc qui reste identique d’une requête à l’autre, et chaque requête suivante lira cette même entrée. Si un bloc ultérieur varie à chaque requête (un horodatage, le message entrant), placez le point d’arrêt avant celui-ci, sur le dernier bloc stable.
Vous n’avez besoin de plusieurs points d’arrêt que si :
* Une conversation qui s’allonge repousse votre point d’arrêt de 20 blocs ou plus au-delà de la dernière écriture dans le cache, plaçant l’entrée précédente hors de la fenêtre de recherche rétrospective
* Vous souhaitez mettre en cache indépendamment des sections mises à jour à des fréquences différentes
* Vous avez besoin d’un contrôle explicite sur ce qui est mis en cache pour optimiser les coûts
Exemple : si vous avez des instructions système (qui changent rarement) et un contexte RAG (qui change quotidiennement), vous pouvez utiliser deux points d’arrêt pour les mettre en cache séparément.
Non, les points d’arrêt de cache eux-mêmes sont gratuits. Vous payez uniquement pour :
* L’écriture de contenu dans le cache (25 pour cent de plus que les tokens d’entrée de base pour une TTL de 5 minutes)
* La lecture depuis le cache ([une fraction du prix de base des tokens d’entrée](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#pricing))
* Les tokens d’entrée ordinaires 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 compte.
La réponse d’utilisation comprend trois champs distincts de tokens d’entrée qui, ensemble, représentent votre entrée totale :
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
* `cache_read_input_tokens` : tokens récupérés depuis le cache (tout ce qui précède les points d’arrêt de cache et qui a été mis en cache)
* `cache_creation_input_tokens` : nouveaux tokens écrits dans le cache (aux points d’arrêt de cache)
* `input_tokens` : tokens **après le dernier point d’arrêt de cache** qui ne sont pas mis en cache
**Important :** `input_tokens` ne représente PAS l’ensemble des tokens d’entrée, seulement la partie située après votre dernier point d’arrêt de cache. Si vous avez du contenu mis en cache, `input_tokens` est généralement bien inférieur à votre entrée totale.
**Exemple :** avec un document de 200k tokens mis en cache et une question utilisateur de 50 tokens :
* `cache_read_input_tokens` : 200 000
* `cache_creation_input_tokens` : 0
* `input_tokens` : 50
* **Total :** 200 050 tokens
Cette répartition est essentielle pour comprendre à la fois vos coûts et votre utilisation des limites de débit. Consultez [Suivi des performances du cache](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#tracking-cache-performance) pour plus de détails.
La durée de vie minimale par défaut du cache (TTL) est de 5 minutes. Cette durée de vie est rafraîchie chaque fois que le contenu mis en cache est utilisé.
Si vous trouvez que 5 minutes sont trop courtes, Anthropic propose également une [TTL de cache de 1 heure](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#1-hour-cache-duration).
La durée de vie est mesurée à partir du début de la requête qui écrit ou lit l’entrée de cache, et non à partir de la fin de sa réponse. Le temps passé à générer une réponse est décompté de la durée de vie, de sorte que la fenêtre permettant à une requête suivante de réutiliser le cache correspond à la durée de vie moins le temps de génération.
Si vos requêtes produisent de longues réponses et que la requête suivante risque de ne commencer qu’après l’expiration de la durée de vie, utilisez la [TTL de cache de 1 heure](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#1-hour-cache-duration).
Vous pouvez définir jusqu’à 4 points d’arrêt de cache (à l’aide des paramètres `cache_control`) dans votre prompt.
La mise en cache des prompts est prise en charge sur tous les [modèles Claude actifs](https://platform.claude.com/docs/fr/models/overview).
Modifier les paramètres de réflexion (changer de mode, ou modifier le budget en mode étendu) invalide les préfixes de messages mis en cache, et peut également invalider les invites système et les outils mis en cache, car la configuration de réflexion est intégrée au prompt. La valeur [`output_config.effort`](https://platform.claude.com/docs/fr/build-with-claude/effort) se comporte de la même manière.
Pour plus de détails sur l’invalidation du cache, consultez [Ce qui invalide le cache](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#what-invalidates-the-cache).
Pour en savoir plus sur la réflexion, y compris son interaction avec l’utilisation d’outils et la mise en cache des prompts, consultez [Réflexion et mise en cache des prompts](https://platform.claude.com/docs/fr/build-with-claude/thinking#thinking-and-prompt-caching).
Le moyen le plus simple consiste à ajouter `"cache_control": {"type": "ephemeral"}` au niveau supérieur du corps de votre requête ([mise en cache automatique](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#automatic-caching)). Vous pouvez également inclure au moins un point d’arrêt `cache_control` sur des blocs de contenu individuels ([points d’arrêt de cache explicites](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#explicit-cache-breakpoints)).
Oui, la mise en cache des prompts peut être utilisée conjointement avec d’autres fonctionnalités de l’API, telles que l’utilisation d’outils et les capacités de vision. Cependant, le fait d’ajouter ou de retirer des images dans un prompt ou de modifier les paramètres d’utilisation d’outils invalide le cache.
Pour plus de détails sur l’invalidation du cache, consultez [Ce qui invalide le cache](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#what-invalidates-the-cache).
La mise en cache des prompts dispose de sa propre tarification : les écritures dans le cache de 5 minutes coûtent 25 pour cent de plus que les tokens d’entrée de base, les écritures dans le cache de 1 heure coûtent 2 fois le prix des tokens d’entrée de base, et les succès de cache coûtent [une fraction du prix de base des tokens d’entrée](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#pricing), avec un multiplicateur propre à chaque modèle.
Actuellement, il n’existe aucun moyen de vider manuellement le cache. Les préfixes mis en cache expirent automatiquement après un minimum de 5 minutes d’inactivité.
Vous pouvez surveiller les performances du cache à l’aide des champs `cache_creation_input_tokens` et `cache_read_input_tokens` dans la réponse de l’API.
Consultez [Ce qui invalide le cache](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#what-invalidates-the-cache) pour plus de détails sur l’invalidation du cache, y compris une liste des modifications qui nécessitent la création d’une nouvelle entrée de cache.
La mise en cache des prompts est conçue avec de solides mesures de confidentialité et de séparation des données :
1. Les clés de cache sont générées à l’aide d’un hachage cryptographique des prompts jusqu’au point de contrôle du cache. Cela signifie que seules les requêtes ayant des prompts identiques peuvent accéder à un cache spécifique.
2. Sur l’API Claude, Claude Platform on AWS et Microsoft Foundry, les caches sont isolés par espace de travail au sein d’une organisation. Sur Claude Models on Google Cloud (Google managed) et Bedrock, les caches sont isolés par organisation. Dans tous les cas, les caches ne sont jamais partagés entre organisations, même pour des prompts identiques. Consultez [Stockage et partage du cache](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#cache-storage-and-sharing) pour plus de détails.
3. Le mécanisme de mise en cache est conçu pour préserver l’intégrité et la confidentialité de chaque conversation ou contexte unique.
4. Vous pouvez utiliser `cache_control` en toute sécurité n’importe où dans vos prompts. Pour que la mise en cache produise des lectures, placez le point d’arrêt à la fin d’un préfixe stable : le placer sur un bloc qui change à chaque requête (comme un horodatage ou la saisie arbitraire de l’utilisateur) écrit une nouvelle entrée à chaque fois sans jamais produire de succès de cache.
Ces mesures garantissent que la mise en cache des prompts préserve la confidentialité et la sécurité des données tout en offrant des avantages en matière de performances.
Oui, vous pouvez utiliser la mise en cache des prompts avec vos requêtes [API Message Batches](https://platform.claude.com/docs/fr/build-with-claude/batch-processing). Cependant, comme les requêtes de lots asynchrones peuvent être traitées simultanément et dans n’importe quel ordre, les succès de cache sont fournis dans la mesure du possible.
Le [cache de 1 heure](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#1-hour-cache-duration) peut aider à améliorer vos succès de cache. La manière la plus rentable de l’utiliser est la suivante :
* Rassemblez un ensemble de requêtes de messages partageant un préfixe commun.
* Envoyez une requête de lot contenant une seule requête avec ce préfixe commun et un bloc de cache de 1 heure. Cela écrit le préfixe dans le cache de 1 heure.
* Dès que celle-ci est terminée, soumettez le reste des requêtes. Vous devez surveiller la tâche pour savoir quand elle se termine.
C’est généralement préférable à l’utilisation du cache de 5 minutes, car il est courant que les requêtes de lots prennent entre 5 minutes et 1 heure pour se terminer.
Cette erreur apparaît généralement lorsque vous avez mis à niveau votre SDK ou que vous utilisez des exemples de code obsolètes. La mise en cache des prompts est disponible sur `client.messages`, sans le préfixe beta. Au lieu de :
```python Python
client.beta.prompt_caching.messages.create(**params)
```
Utilisez :
```python Python
client.messages.create(**params)
```
Cette erreur apparaît généralement lorsque vous avez mis à niveau votre SDK ou que vous utilisez des exemples de code obsolètes. La mise en cache des prompts est disponible sur `client.messages`, sans le préfixe beta. Au lieu de :
```typescript TypeScript
client.beta.promptCaching.messages.create(/* ... */);
```
Utilisez :
```typescript
client.messages.create(/* ... */);
```
## Disponibilité
Mise en cache des prompts est disponible ou en bêta, selon l’API, et éligible aux dispositifs suivants : zéro conservation des données et préparation HIPAA.
### Prise en charge de l’API
#### [Messages API](https://platform.claude.com/docs/fr/build-with-claude/working-with-messages)
* Disponibilité : Disponible
* Utilisation : Activez-la avec `cache_control`, au niveau supérieur ou sur des blocs.
| Statut | Plateformes cloud | Modèles |
| ---------- | --------------------------------------- | ----------------------------------------------------------------------- |
| Disponible | Toutes les plateformes prises en charge | [Tous les modèles](https://platform.claude.com/docs/fr/models/overview) |
#### [Managed Agents](https://platform.claude.com/docs/fr/managed-agents/overview)
* Disponibilité : Toujours activé
* Utilisation : Les entrées du cache ont une durée de vie de 5 minutes par défaut, et les lectures et écritures du cache apparaissent dans l’utilisation de la session.
| Statut | Plateformes cloud | Modèles |
| ------ | --------------------------------------- | ----------------------------------------------------------------------- |
| Bêta | Toutes les plateformes prises en charge | [Tous les modèles](https://platform.claude.com/docs/fr/models/overview) |
### Traitement des données
[Présentation du traitement des données](https://platform.claude.com/docs/fr/manage-claude/api-and-data-retention#feature-eligibility)
| Élément | Zéro conservation des données | HIPAA |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| Statut | Éligible (exclut [Modèles couverts](https://platform.claude.com/docs/fr/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)) | Éligible |
| Détails | Vos prompts et les sorties de Claude ne sont pas stockés. Les représentations du cache KV et les hachages cryptographiques sont conservés en mémoire pendant la durée de vie du cache et supprimés rapidement après son expiration. [En savoir plus](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#data-retention) | — |
Points de terminaison concernés :
* `/v1/messages`