---
title: Orienter la réflexion
url: https://platform.claude.com/docs/fr/build-with-claude/thinking-steering-and-cost
description: Orientez la fréquence et la profondeur de la réflexion de Claude grâce aux niveaux d'effort, aux consignes dans l'invite système et à l'orientation par message, et comprenez le coût et la tarification de la réflexion.
---
Pour savoir comment la « zero data retention » (rétention zéro des données), ou ZDR, s'applique à cette fonctionnalité, consultez [API et rétention des données](https://platform.claude.com/docs/fr/manage-claude/api-and-data-retention).
La réflexion de Claude est adaptative : le modèle évalue chaque requête et détermine s'il doit réfléchir et dans quelle mesure. Vous définissez une intention, spécifiez éventuellement l'effort, et le modèle alloue du raisonnement là où il juge que le raisonnement sera utile.
Cela fait de la réflexion un excellent choix pour les charges de travail qui mélangent des requêtes triviales et complexes, ainsi que pour les flux de travail agentiques à long horizon où la bonne quantité de raisonnement varie d'une étape à l'autre.
Pour savoir comment activer la réflexion, comment lire la sortie de réflexion, et pour en savoir plus sur [la sortie de réflexion sur Claude Fable 5 et Claude Mythos 5](https://platform.claude.com/docs/fr/build-with-claude/thinking#thinking-output-on-claude-fable-5-and-claude-mythos-5), consultez la vue d'ensemble [Réflexion](https://platform.claude.com/docs/fr/build-with-claude/thinking). Cette page explique comment Claude détermine quand réfléchir, comment orienter la réflexion, ainsi que les mécanismes de mise en cache, de coût et de tarification qui en découlent.
## Comment Claude détermine quand réfléchir
La réflexion est facultative pour le modèle. À chaque requête, Claude évalue la complexité de l'entrée et détermine si un raisonnement plus approfondi améliorerait la réponse. Une simple question factuelle peut recevoir une réponse directe sans aucun bloc de réflexion ; un problème mathématique en plusieurs étapes ou une tâche de débogage délicate déclenche un raisonnement plus approfondi.
La décision se prend requête par requête. Une même conversation peut contenir des tours avec et sans réflexion, et un tour où Claude a choisi de ne pas réfléchir ne contient aucun bloc de réflexion. Ne construisez pas de logique applicative qui suppose que chaque tour de l'assistant commence par un tel bloc.
Le principal contrôle sur cette décision est le paramètre [effort](https://platform.claude.com/docs/fr/build-with-claude/effort), qui agit comme une indication souple de la propension de Claude à réfléchir et de la profondeur de cette réflexion ; consultez la section [Niveaux d'effort](https://platform.claude.com/docs/fr/build-with-claude/thinking-steering-and-cost#effort-levels) de cette page pour savoir ce que fait chaque niveau.
Si vous souhaitez que Claude réfléchisse moins souvent, abaissez le niveau d'effort avant de recourir à l'orientation par prompt.
La réflexion s'entrelace également automatiquement avec le « tool use » (utilisation d'outils) : Claude peut réfléchir entre les appels d'outils, en analysant chaque résultat d'outil avant de déterminer la suite ([réflexion entrelacée](https://platform.claude.com/docs/fr/build-with-claude/thinking#interleaved-thinking)). Vous n'avez besoin d'aucun en-tête bêta ni d'aucune configuration supplémentaire pour cela.
Pour une vue complète de la manière dont la configuration de la réflexion et le paramètre d'effort interagissent, consultez [Réflexion et effort](https://platform.claude.com/docs/fr/build-with-claude/thinking#thinking-and-effort).
## Orienter la fréquence de réflexion de Claude
Le fait que Claude réfléchisse ou non lors d'un tour donné peut être influencé par le prompt. L'effort définit la posture générale, mais vous pouvez également façonner directement la décision avec des consignes en langage naturel, soit globalement dans l'« system prompt » (invite système), soit par message depuis le tour de l'utilisateur.
Utilisez les deux leviers ensemble dans cet ordre :
1. Définissez le niveau d'effort qui correspond à l'équilibre par défaut entre qualité et latence de votre charge de travail.
2. N'ajoutez des consignes dans le prompt que si le déclenchement de la réflexion par Claude ne correspond toujours pas à vos besoins à ce niveau.
Pour obtenir moins de réflexion sur Claude Sonnet 5.5 et Claude Haiku 5.5, abaissez le niveau d'effort. Demander à Claude Sonnet 5.5 dans l'invite système de moins réfléchir ne réduit pas sa réflexion de manière fiable, et lors des tests d'Anthropic, demander à Claude Haiku 5.5 dans le prompt de répondre directement ne l'a pas empêché de réfléchir. Consultez [Rédiger des prompts pour Claude Sonnet 5.5](https://platform.claude.com/docs/fr/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#calibrate-effort) et [Rédiger des prompts pour Claude Haiku 5.5](https://platform.claude.com/docs/fr/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking).
Pour des conseils plus généraux sur le prompting avec la réflexion, consultez [tirer parti des capacités de réflexion et de réflexion entrelacée](https://platform.claude.com/docs/fr/build-with-claude/prompt-engineering/claude-prompting-best-practices#leverage-thinking-and-interleaved-thinking-capabilities).
### Niveaux d'effort
L'effort est le principal levier d'orientation de la réflexion. Chaque niveau définit un comportement par défaut différent quant à la fréquence et à la profondeur de la réflexion de Claude :
| Niveau d'effort | Comportement de réflexion |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `max` | Claude réfléchit le plus volontiers et avec la plus grande profondeur, sans contrainte sur la longueur de la réflexion. |
| `xhigh` | Claude réfléchit plus volontiers et plus en profondeur qu'au niveau `high`, ce qui convient à une exploration approfondie. |
| `high` (par défaut sur la plupart des modèles) | Claude réfléchit sur la plupart des requêtes qui en bénéficient. Fournit un raisonnement approfondi sur les tâches complexes. |
| `medium` (par défaut sur Claude Opus 5.5 et Claude Haiku 5.5) | Claude utilise une réflexion modérée. Peut ignorer la réflexion pour les requêtes simples. |
| `low` | Claude réduit la réflexion au minimum. Ignore la réflexion pour les tâches simples où la vitesse compte le plus. |
À chaque niveau, Claude détermine par requête s'il doit réfléchir. Dans une boucle d'utilisation d'outils, la première requête après une nouvelle entrée de l'utilisateur porte généralement l'essentiel du raisonnement, et les requêtes suivantes qui ne font que traiter des résultats d'outils peuvent ignorer la réflexion, y compris aux niveaux `xhigh` et `max`. La réflexion par requête tend également à diminuer à mesure qu'une conversation s'allonge. Aucun niveau ne garantit un bloc de réflexion à chaque requête.
Ce tableau décrit comment chaque niveau modifie le comportement de réflexion. Pour savoir quel niveau choisir pour une charge de travail donnée, consultez [Quand ajuster le paramètre effort](https://platform.claude.com/docs/fr/build-with-claude/effort#when-to-adjust-the-effort-parameter) sur la page consacrée à l'effort. Cette section inclut aussi des recommandations par modèle.
L'effort se définit dans `output_config.effort`, et non dans l'objet `thinking` ; pour des exemples complets dans chaque langage, consultez [Effort](https://platform.claude.com/docs/fr/build-with-claude/effort#basic-usage).
```json
{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"output_config": { "effort": "medium" },
"messages": [{ "role": "user", "content": "..." }]
}
```
La disponibilité des niveaux varie selon le modèle. Le [tableau de disponibilité de l'effort](https://platform.claude.com/docs/fr/build-with-claude/effort#effort-levels), sur la page consacrée à l'effort, fait référence pour savoir quels niveaux chaque modèle prend en charge.
### Consignes dans l'invite système
Les consignes dans l'invite système déplacent le seuil de réflexion de Claude pour chaque requête de la conversation. Si Claude réfléchit plus souvent que votre charge de travail ne le nécessite, ajoutez des consignes comme celles-ci à votre invite système :
```text wrap
Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality, typically for problems
that require multistep reasoning. When in doubt, respond directly.
```
Pour encourager la réflexion au contraire, utilisez une formulation comme :
```text wrap
This task involves multistep reasoning. Think carefully before responding.
```
L'efficacité de l'orientation peut être sensible à la formulation exacte. Si une formulation ne produit pas le comportement souhaité, essayez une variante plus directe.
### Orientation par message
Vous pouvez également orienter la réflexion message par message depuis le tour de l'utilisateur, indépendamment de l'invite système. Ajouter `"Please think hard before responding."` à un message utilisateur encourage Claude à réfléchir lors de ce tour ; `"Answer directly without deliberating."` l'en dissuade.
L'orientation par message est utile lorsque seules certaines requêtes d'une conversation justifient un raisonnement approfondi. Un harnais d'agent, par exemple, peut ajouter la formulation incitative lors des étapes de planification et la formulation dissuasive lors des confirmations de routine, sans toucher à l'invite système ni modifier aucun paramètre de requête entre les tours.
Sur Claude Haiku 5.5, la formulation dissuasive ne réduit pas la réflexion de manière fiable. Sur l'API Claude et Google Cloud, exécutez plutôt les tours de routine sur ce modèle avec moins de réflexion en utilisant un [changement d'effort par message](https://platform.claude.com/docs/fr/build-with-claude/effort#change-effort-mid-conversation-beta) (bêta), qui préserve également le cache des prompts.
### Vérifier l'orientation sur votre charge de travail
L'orientation par prompt modifie le comportement du modèle ; traitez-la donc comme toute autre modification de prompt : mesurez avant de déployer. Exécutez un échantillon représentatif de votre trafic avec et sans les consignes, et comparez la fréquence de déclenchement de la réflexion (la présence de blocs de réflexion dans les réponses), la consommation de tokens de sortie, la latence et la qualité des réponses sur les cas qui comptent pour vous.
Orienter Claude pour qu'il réfléchisse moins souvent peut réduire la qualité sur les tâches qui bénéficient du raisonnement. Abaisser le niveau d'[effort](https://platform.claude.com/docs/fr/build-with-claude/effort) est généralement le meilleur premier levier, car il s'agit d'un contrôle calibré plutôt que d'une instruction sensible à la formulation. Mesurez l'impact sur vos charges de travail spécifiques avant de déployer un ajustement par prompt en production.
## Mécanismes
Trois mécanismes découlent du fait que Claude gère sa propre réflexion : la validation des tours, la mise en cache des prompts et la manière dont vous bornez le coût.
### Validation des tours
Les tours de l'assistant n'ont pas besoin de commencer par un bloc de réflexion. (Les modèles utilisant un ancien budget de réflexion manuel imposent que le dernier tour de l'assistant d'une requête avec réflexion activée commence par un tel bloc ; consultez [Structure des tours en mode manuel](https://platform.claude.com/docs/fr/build-with-claude/extended-thinking#turn-structure-in-manual-mode).)
Pour les applications multi-tours, cela signifie que vous pouvez renvoyer l'historique de conversation sous la forme dont vous disposez :
* Les tours de l'assistant où Claude a choisi de ne pas réfléchir constituent un historique valide tel quel.
* Vous pouvez reprendre une conversation qui a commencé sans réflexion, ou qui utilisait une configuration de réflexion différente, sans réécrire son historique.
* Un historique assemblé à partir de sources mixtes n'a pas besoin que des blocs de réflexion soient réinsérés au début de chaque tour de l'assistant pour passer la validation.
Cet assouplissement concerne la validation, et non ce que vous devriez envoyer. Lorsque vous disposez de blocs de réflexion, renvoyez-les sans modification, en particulier lors de l'utilisation d'outils, où ils portent le raisonnement derrière les appels d'outils de Claude. Consultez la vue d'ensemble [Réflexion](https://platform.claude.com/docs/fr/build-with-claude/thinking) pour les règles complètes.
### Mise en cache des prompts
Les requêtes consécutives qui conservent la même configuration de réflexion et le même niveau d'effort préservent 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) pour les règles complètes. La valeur d'effort résolue est intégrée au prompt : la modifier entre les requêtes invalide donc les points d'arrêt de cache. Il en va de même lorsque vous modifiez l'ancien paramètre [`budget_tokens`](https://platform.claude.com/docs/fr/build-with-claude/extended-thinking#extended-thinking-with-prompt-caching) sur les modèles qui l'utilisent. Définir explicitement `effort` sur la valeur par défaut du modèle équivaut à l'omettre et n'invalide pas le cache.
Conséquence pratique : choisissez une configuration de réflexion et une valeur d'effort de niveau supérieur par conversation, et conservez-les. Si certains tours nécessitent plus ou moins de réflexion, utilisez un [changement d'effort par message](https://platform.claude.com/docs/fr/build-with-claude/effort#change-effort-mid-conversation-beta) (bêta) sur les modèles qui le prennent en charge, ou orientez-la avec le [prompting par message](https://platform.claude.com/docs/fr/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior). Ces deux approches laissent intacts les points d'arrêt de cache antérieurs, contrairement à une modification de la configuration de réflexion ou de la valeur d'effort de niveau supérieur.
L'exemple suivant illustre l'invalidation avec un script multi-tours que vous pouvez exécuter vous-même :
Ce flux de travail se prête mal à une commande shell ponctuelle. Consultez les onglets SDK pour le modèle multi-tours ; les requêtes HTTP par tour suivent les exemples de la page [Mise en cache des prompts](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching).
Ce flux de travail se prête mal à une commande shell ponctuelle. Consultez les onglets SDK pour le modèle multi-tours ; les invocations CLI par tour suivent les exemples de la page [Mise en cache des prompts](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching).
```python
import requests
client = Anthropic()
def fetch_article_content(url):
text = requests.get(url).text
lines = (line.strip() for line in text.splitlines())
return "\n".join(line for line in lines if line)
# Récupérer le contenu de l'article.
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Utiliser juste assez de texte pour la mise en cache (premiers chapitres).
LARGE_TEXT = book_content[:10000]
# Pas d'invite système : mise en cache dans les messages à la place.
MESSAGES = [
{
"role": "user",
"content": [
{
"type": "text",
"text": LARGE_TEXT,
"cache_control": {"type": "ephemeral"},
},
{"type": "text", "text": "Analyze the tone of this passage."},
],
}
]
# Première requête : établir le cache.
print("First request - establishing cache")
response1 = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive"},
messages=MESSAGES,
)
print(f"First response usage: {response1.usage}")
MESSAGES.append({"role": "assistant", "content": response1.content})
MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."})
# Deuxième requête : même configuration (succès de cache attendu).
print("\nSecond request - same configuration (cache hit expected)")
response2 = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive"},
messages=MESSAGES,
)
print(f"Second response usage: {response2.usage}")
MESSAGES.append({"role": "assistant", "content": response2.content})
MESSAGES.append({"role": "user", "content": "Analyze the setting in this passage."})
# Troisième requête : niveau d'effort différent (échec de cache attendu).
print("\nThird request - different effort level (cache miss expected)")
response3 = client.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
thinking={"type": "adaptive"},
output_config={"effort": "low"},
messages=MESSAGES,
)
print(f"Third response usage: {response3.usage}")
```
```typescript
const client = new Anthropic();
async function fetchArticleContent(url: string): Promise {
const response = await fetch(url);
const text = await response.text();
const lines = text.split("\n").map((line) => line.trim());
return lines.filter((line) => line).join("\n");
}
const bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
const bookContent = await fetchArticleContent(bookUrl);
const LARGE_TEXT = bookContent.substring(0, 10000);
// Pas d'invite système : mise en cache dans les messages à la place.
const messages: Anthropic.MessageParam[] = [
{
role: "user",
content: [
{
type: "text",
text: LARGE_TEXT,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
}
];
// Première requête : établir le cache.
console.log("First request - establishing cache");
const response1 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: { type: "adaptive" },
messages
});
console.log("First response usage: ", response1.usage);
messages.push(
{ role: "assistant", content: response1.content },
{ role: "user", content: "Analyze the characters in this passage." }
);
// Deuxième requête : même configuration (succès de cache attendu).
console.log("\nSecond request - same configuration (cache hit expected)");
const response2 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: { type: "adaptive" },
messages
});
console.log("Second response usage: ", response2.usage);
messages.push(
{ role: "assistant", content: response2.content },
{ role: "user", content: "Analyze the setting in this passage." }
);
// Troisième requête : niveau d'effort différent (échec de cache attendu).
console.log("\nThird request - different effort level (cache miss expected)");
const response3 = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: { type: "adaptive" },
output_config: { effort: "low" },
messages
});
console.log("Third response usage: ", response3.usage);
```
```csharp
AnthropicClient client = new();
string bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
string bookContent = await FetchArticleContent(bookUrl);
string largeText = bookContent.Substring(0, Math.Min(10000, bookContent.Length));
Console.WriteLine("First request - establishing cache");
var parameters1 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
Thinking = new ThinkingConfigAdaptive(),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = largeText,
CacheControl = new CacheControlEphemeral(),
}),
new ContentBlockParam(new TextBlockParam()
{
Text = "Analyze the tone of this passage."
}),
})
}
]
};
var response1 = await client.Messages.Create(parameters1);
Console.WriteLine($"First response usage: {response1.Usage}");
Console.WriteLine("\nSecond request - same configuration (cache hit expected)");
var parameters2 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
Thinking = new ThinkingConfigAdaptive(),
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = largeText,
CacheControl = new CacheControlEphemeral(),
}),
new ContentBlockParam(new TextBlockParam()
{
Text = "Analyze the tone of this passage."
}),
})
},
new()
{
Role = Role.Assistant,
Content = response1.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
},
new()
{
Role = Role.User,
Content = "Analyze the characters in this passage."
}
]
};
var response2 = await client.Messages.Create(parameters2);
Console.WriteLine($"Second response usage: {response2.Usage}");
Console.WriteLine("\nThird request - different effort level (cache miss expected)");
var parameters3 = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 16000,
Thinking = new ThinkingConfigAdaptive(),
OutputConfig = new OutputConfig
{
Effort = Effort.Low
},
Messages =
[
new()
{
Role = Role.User,
Content = new MessageParamContent(new List
{
new ContentBlockParam(new TextBlockParam()
{
Text = largeText,
CacheControl = new CacheControlEphemeral(),
}),
new ContentBlockParam(new TextBlockParam()
{
Text = "Analyze the tone of this passage."
}),
})
},
new()
{
Role = Role.Assistant,
Content = response1.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
},
new()
{
Role = Role.User,
Content = "Analyze the characters in this passage."
},
new()
{
Role = Role.Assistant,
Content = response2.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
},
new()
{
Role = Role.User,
Content = "Analyze the setting in this passage."
}
]
};
var response3 = await client.Messages.Create(parameters3);
Console.WriteLine($"Third response usage: {response3.Usage}");
static async Task FetchArticleContent(string url)
{
using HttpClient httpClient = new();
string content = await httpClient.GetStringAsync(url);
return content;
}
```
```go
client := anthropic.NewClient()
bookURL := "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
bookContent, err := fetchArticleContent(bookURL)
if err != nil {
log.Fatal(err)
}
largeText := bookContent
if len(largeText) > 10000 {
largeText = largeText[:10000]
}
// Pas d'invite système : mise en cache dans les messages à la place.
messages := []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{
Text: largeText,
CacheControl: anthropic.NewCacheControlEphemeralParam(),
}},
anthropic.NewTextBlock("Analyze the tone of this passage."),
),
}
// Première requête : établir le cache.
fmt.Println("First request - establishing cache")
response1, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("First response usage: %s\n", response1.Usage.RawJSON())
messages = append(messages, response1.ToParam())
messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the characters in this passage.")))
// Deuxième requête : même configuration (succès de cache attendu).
fmt.Println("\nSecond request - same configuration (cache hit expected)")
response2, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Second response usage: %s\n", response2.Usage.RawJSON())
messages = append(messages, response2.ToParam())
messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the setting in this passage.")))
// Troisième requête : niveau d'effort différent (échec de cache attendu).
fmt.Println("\nThird request - different effort level (cache miss expected)")
response3, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 16000,
Thinking: anthropic.ThinkingConfigParamUnion{
OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},
},
OutputConfig: anthropic.OutputConfigParam{
Effort: anthropic.OutputConfigEffortLow,
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Third response usage: %s\n", response3.Usage.RawJSON())
```
```java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
void main() throws Exception {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
String bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
String bookContent = fetchArticleContent(bookUrl);
String largeText = bookContent.substring(0, Math.min(10000, bookContent.length()));
// Première requête - établissement du cache
IO.println("First request - establishing cache");
MessageCreateParams params1 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text(largeText)
.cacheControl(CacheControlEphemeral.builder().build())
.build()),
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Analyze the tone of this passage.")
.build())
))
.build();
Message response1 = client.messages().create(params1);
IO.println("First response usage: " + response1.usage());
// Deuxième requête - même configuration (cache hit attendu)
IO.println("\nSecond request - same configuration (cache hit expected)");
MessageCreateParams params2 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text(largeText)
.cacheControl(CacheControlEphemeral.builder().build())
.build()),
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Analyze the tone of this passage.")
.build())
))
.addAssistantMessageOfBlockParams(response1.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the characters in this passage.")
.build();
Message response2 = client.messages().create(params2);
IO.println("Second response usage: " + response2.usage());
// Troisième requête - niveau d'effort différent (cache miss attendu)
IO.println("\nThird request - different effort level (cache miss expected)");
MessageCreateParams params3 = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(16000L)
.thinking(ThinkingConfigAdaptive.builder().build())
.outputConfig(OutputConfig.builder()
.effort(OutputConfig.Effort.LOW)
.build())
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofText(TextBlockParam.builder()
.text(largeText)
.cacheControl(CacheControlEphemeral.builder().build())
.build()),
ContentBlockParam.ofText(TextBlockParam.builder()
.text("Analyze the tone of this passage.")
.build())
))
.addAssistantMessageOfBlockParams(response1.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the characters in this passage.")
.addAssistantMessageOfBlockParams(response2.content().stream()
.map(block -> block.toParam())
.collect(java.util.stream.Collectors.toList()))
.addUserMessage("Analyze the setting in this passage.")
.build();
Message response3 = client.messages().create(params3);
IO.println("Third response usage: " + response3.usage());
}
String fetchArticleContent(String url) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
return response.body();
}
```
```php
function fetchArticleContent($url) {
$content = file_get_contents($url);
$lines = explode("\n", $content);
$cleanedLines = array_filter(array_map('trim', $lines));
return implode("\n", $cleanedLines);
}
$client = new Client();
$bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";
$bookContent = fetchArticleContent($bookUrl);
$largeText = substr($bookContent, 0, 10000);
echo "First request - establishing cache\n";
$response1 = $client->messages->create(
maxTokens: 16000,
messages: [[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => $largeText,
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'text' => 'Analyze the tone of this passage.'
]
]
]],
model: 'claude-opus-5-5',
thinking: ['type' => 'adaptive'],
);
echo "First response usage: " . json_encode($response1->usage) . "\n";
echo "\nSecond request - same configuration (cache hit expected)\n";
$response2 = $client->messages->create(
maxTokens: 16000,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => $largeText,
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'text' => 'Analyze the tone of this passage.'
]
]
],
[
'role' => 'assistant',
'content' => $response1->content
],
[
'role' => 'user',
'content' => 'Analyze the characters in this passage.'
]
],
model: 'claude-opus-5-5',
thinking: ['type' => 'adaptive'],
);
echo "Second response usage: " . json_encode($response2->usage) . "\n";
echo "\nThird request - different effort level (cache miss expected)\n";
$response3 = $client->messages->create(
maxTokens: 16000,
messages: [
[
'role' => 'user',
'content' => [
[
'type' => 'text',
'text' => $largeText,
'cache_control' => ['type' => 'ephemeral']
],
[
'type' => 'text',
'text' => 'Analyze the tone of this passage.'
]
]
],
[
'role' => 'assistant',
'content' => $response1->content
],
[
'role' => 'user',
'content' => 'Analyze the characters in this passage.'
],
[
'role' => 'assistant',
'content' => $response2->content
],
[
'role' => 'user',
'content' => 'Analyze the setting in this passage.'
]
],
model: 'claude-opus-5-5',
thinking: ['type' => 'adaptive'],
outputConfig: ['effort' => 'low'],
);
echo "Third response usage: " . json_encode($response3->usage) . "\n";
```
```ruby
require "net/http"
require "uri"
def fetch_article_content(url)
uri = URI.parse(url)
response = Net::HTTP.get_response(uri)
text = response.body
lines = text.split("\n").map(&:strip)
lines.reject(&:empty?).join("\n")
end
client = Anthropic::Client.new
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
large_text = book_content[0...10000]
puts "First request - establishing cache"
response1 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
messages: [{
role: "user",
content: [
{
type: "text",
text: large_text,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
}]
)
puts "First response usage: #{response1.usage}"
puts "\nSecond request - same configuration (cache hit expected)"
response2 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
messages: [
{
role: "user",
content: [
{
type: "text",
text: large_text,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
},
{
role: "assistant",
content: response1.content
},
{
role: "user",
content: "Analyze the characters in this passage."
}
]
)
puts "Second response usage: #{response2.usage}"
puts "\nThird request - different effort level (cache miss expected)"
response3 = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 16000,
thinking: {
type: "adaptive"
},
output_config: {
effort: "low"
},
messages: [
{
role: "user",
content: [
{
type: "text",
text: large_text,
cache_control: { type: "ephemeral" }
},
{
type: "text",
text: "Analyze the tone of this passage."
}
]
},
{
role: "assistant",
content: response1.content
},
{
role: "user",
content: "Analyze the characters in this passage."
},
{
role: "assistant",
content: response2.content
},
{
role: "user",
content: "Analyze the setting in this passage."
}
]
)
puts "Third response usage: #{response3.usage}"
```
Voici la sortie du script (vous pourriez voir des chiffres légèrement différents) :
```text Output wrap
First request - establishing cache
First response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 15, output_tokens: 1033 }
Second request - same configuration (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 3546, input_tokens: 1062, output_tokens: 1630 }
Third request - different effort level (cache miss expected)
Third response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 2706, output_tokens: 1468 }
```
Avec le point d'arrêt de cache dans le tableau messages, faire passer l'effort de `medium`, la valeur par défaut sur Claude Opus 5.5, à `low` l'invalide : la troisième requête affiche `cache_creation_input_tokens=3546` et `cache_read_input_tokens=0`, là où la deuxième affichait une lecture complète du cache.
### Contrôle des coûts
Vous ne définissez pas de budget de tokens de réflexion. Deux contrôles bornent le coût :
* `max_tokens` est un plafond strict sur la sortie totale de la requête, réflexion et texte de réponse combinés. Claude ne génère jamais au-delà. Dans une boucle d'utilisation d'outils, chaque requête du tour possède son propre `max_tokens`, de sorte qu'il ne borne pas la dépense de l'ensemble du tour.
* `effort` est une indication souple de la part de cette sortie que Claude alloue à la réflexion. Il façonne le comportement mais ne garantit pas un nombre de tokens.
Comme la réflexion est comptabilisée dans `max_tokens`, définissez-le suffisamment haut pour laisser de la place à la fois au raisonnement et à la réponse. Un `max_tokens` dimensionné pour une réponse sans réflexion est souvent trop petit dès que Claude commence à réfléchir sur des requêtes difficiles.
À l'effort `high` et au-delà, Claude peut réfléchir longuement et est plus susceptible d'épuiser le budget. Si vous voyez [`stop_reason: "max_tokens"`](https://platform.claude.com/docs/fr/build-with-claude/thinking-troubleshooting#stopped-at-max-tokens) dans les réponses, vous disposez de deux remèdes :
* Augmentez `max_tokens` pour donner au modèle plus de place pour la réflexion et la réponse.
* Abaissez le niveau d'effort afin que Claude réfléchisse moins et laisse une plus grande part du budget au texte de réponse.
Le bon choix dépend de la question de savoir si les réponses tronquées avaient besoin du raisonnement. Si la qualité sur ces requêtes compte, augmentez le plafond ; si elles étaient sur-réfléchies, abaissez l'effort.
## Tarification
La réflexion entraîne des frais pour :
* Les tokens que Claude utilise pendant la réflexion (facturés comme tokens de sortie)
* Les blocs de réflexion des tours précédents de l'assistant qui restent dans le contexte, selon la [préservation par défaut](https://platform.claude.com/docs/fr/build-with-claude/thinking#thinking-block-preservation-by-model) : tous les tours par défaut sur les modèles qui conservent tout, uniquement le dernier tour ailleurs (facturés comme tokens d'entrée)
* Les tokens de sortie de texte standard
Lorsque la réflexion est active, une invite système spécialisée est automatiquement incluse pour prendre en charge cette fonctionnalité.
Ce qui vous est facturé est identique quel que soit le paramètre `display` ; seul ce que vous voyez change :
| | `display: "summarized"` | `display: "omitted"` |
| ------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------ |
| **Tokens d'entrée** | Tokens de votre requête d'origine | Identique à summarized |
| **Tokens de sortie (facturés)** | L'intégralité des tokens de réflexion que Claude a générés en interne | Identique à summarized |
| **Tokens de sortie (visibles)** | Le texte de réflexion résumé | Zéro token de réflexion (le champ `thinking` est vide) |
| **Génération du résumé** | Sans frais | Non applicable |
Le nombre de tokens de sortie facturés ne correspond **pas** au nombre de tokens visibles dans la réponse. Vous êtes facturé pour l'intégralité du processus de réflexion, et non pour le contenu de réflexion visible dans la réponse.
Pour voir combien de tokens de sortie facturés ont été consacrés au raisonnement interne, lisez `usage.output_tokens_details.thinking_tokens` dans la réponse. Cette valeur reflète le raisonnement brut généré par le modèle (et non le texte résumé renvoyé dans le corps) et est toujours inférieure ou égale à `output_tokens`. Soustrayez-la de `output_tokens` pour estimer la part de la sortie hors raisonnement. En streaming, cette ventilation n'apparaît que dans l'événement final `message_delta`.
```json
{
"usage": {
"input_tokens": 25,
"output_tokens": 348,
"output_tokens_details": {
"thinking_tokens": 312
}
}
}
```
`output_tokens` reste le total inclusif faisant autorité pour la facturation. `output_tokens_details` est une ventilation en lecture seule à des fins d'observabilité. Pour des informations tarifaires complètes, y compris les tarifs de base, les écritures en cache, les lectures en cache et les tokens de sortie, consultez [Tarification](https://platform.claude.com/docs/fr/about-claude/pricing).
## Étapes suivantes
Activez la réflexion, lisez la sortie de réflexion et vérifiez la prise en charge par modèle.
Préservez les blocs de réflexion entre les appels d'outils et gérez la réflexion dans les conversations multi-tours.
Contrôlez la quantité de réflexion et de sortie que Claude alloue par requête.