Effort de raisonnement et tokens de réflexion : pourquoi la réflexion coûte plus cher

Votre requête était une simple question factuelle. La réponse tenait en trois lignes. Le compteur de sortie affiche des milliers de tokens. Ce n'est pas un bug : avant de répondre, de nombreux modèles réfléchissent dans un brouillon caché, et ces tokens de réflexion sont facturés comme des tokens de sortie. Le réglage effort détermine la part de cette réflexion, et max_tokens doit lui laisser de la place, sinon vous obtenez une réponse tronquée ou vide.

Ce que fait le modèle avant de répondre#

Pensez à un examen. Vous pouvez écrire la réponse directement, ou remplir d'abord une page de brouillon. Le brouillon donne souvent un meilleur résultat sur un problème difficile, mais le papier n'est pas gratuit. Le raisonnement, c'est ce brouillon, et il est compté en tokens comme tout le reste.

La documentation d'Anthropic sur la réflexion étendue (consultée le 23 octobre 2026) indique que les tokens de réflexion font partie des tokens de sortie facturés, et la réponse vous dit combien : usage.output_tokens_details.thinking_tokens. Supposons qu'une réponse revienne avec ce bloc d'utilisation (chiffres d'exemple) :

"usage": {
  "input_tokens": 480,
  "output_tokens": 2150,
  "output_tokens_details": { "thinking_tokens": 1900 }
}

Vous êtes facturé pour 2 150 tokens de sortie. La réflexion en a pris 1 900, donc le texte que vous lisez réellement fait 2 150 − 1 900 = 250 tokens. Il en va de même même lorsque le texte de réflexion ne vous est pas renvoyé : il compte quand même. Si vous voulez d'abord la différence entre entrée et sortie, commencez par tokens d'entrée vs de sortie.

Effort : le bouton de réglage de la réflexion#

Dans l'API de Claude, le bouton est output_config.effort. La page d'Anthropic sur l'effort (consultée le 23 octobre 2026) liste cinq niveaux : low, medium, high, xhigh, max. Trois détails comptent pour un débutant :

• Il affecte chaque token de sortie, pas seulement la réflexion : texte, appels d'outils et réflexion ensemble.
• C'est un signal comportemental, pas un budget strict. Un effort plus faible signifie moins de tokens au prix d'une certaine capacité ; à faible effort, Claude peut sauter complètement la réflexion sur un problème simple.
• La valeur par défaut est medium sur Claude Opus 5.5 et Claude Haiku 5.5, et high sur la plupart des autres modèles qui prennent en charge le paramètre. Définir explicitement la valeur par défaut revient à l'omettre.

Les niveaux sont recalibrés par modèle, donc high sur un modèle ne correspond pas à la même quantité de réflexion que high sur un autre, et tous les modèles n'acceptent pas tous les niveaux. Dans une vidéo publiée, quelqu'un a exécuté tous les niveaux d'effort de Claude Opus 5.5 sur la même tâche de motion design et comparé les images. C'est un bon moyen de voir ce qu'apporte plus de réflexion. Cela ne vous dira pas votre facture, car votre tâche n'est pas la leur.

Une requête pour une question simple, avec l'effort réduit :

{
  "model": "claude-opus-5-5",
  "max_tokens": 4000,
  "output_config": { "effort": "low" },
  "messages": [
    { "role": "user", "content": "What is the capital of Australia?" }
  ]
}

Le piège de la réponse vide : la réflexion compte dans max_tokens#

Voici comment cela tourne mal. Vous attendez une réponse de deux phrases, donc vous réglez max_tokens à 300. Le modèle commence à réfléchir, dépense les 300 dans son brouillon, atteint la limite et s'arrête. Vous obtenez une réponse vide ou une phrase qui se termine au milieu d'un mot, et la raison d'arrêt indique max_tokens.

La documentation est explicite : max_tokens est une limite stricte sur la sortie totale, réflexion plus texte de réponse, et la réflexion compte même lorsque son contenu n'est pas renvoyé. À partir de l'effort high et au-dessus, Anthropic recommande de définir une valeur élevée.

En pratique :

1. Prenez la longueur de la réponse que vous voulez.
2. Ajoutez une marge généreuse pour la réflexion. Quelques milliers de tokens est un point de départ raisonnable pour tout ce qui dépasse low.
3. Vérifiez la raison d'arrêt après les premiers essais. Si elle indique encore max_tokens, augmentez la limite. Si la réponse est complète, vous pouvez la baisser.

La troncature elle-même, avec finish_reason et la fenêtre de contexte, est traitée dans pourquoi une réponse IA s'arrête en pleine phrase.

Ce que fait un long raisonnement sur la facture#

Supposons que vous exploitiez un bot de support avec 2 000 tickets par jour. Chaque ticket fait environ 500 tokens en entrée. Une réponse courte et directe fait environ 400 tokens en sortie. Le même ticket avec un long raisonnement caché fait environ 4 000 tokens en sortie. Ce sont des hypothèses pour l'exemple ; pour vos propres chiffres, voir combien de tokens une requête utilise.

Par jour, cela fait 2 000 × 500 = 1 000 000 tokens d'entrée, et soit 2 000 × 400 = 800 000 tokens de sortie, soit 2 000 × 4 000 = 8 000 000 tokens de sortie. Le lecteur du ticket voit les deux mêmes lignes dans les deux cas. La seule chose qui a bougé est le volume de sortie, et c'est la sortie que le raisonnement gonfle.

L'arithmétique est la même sur tout modèle qui facture le raisonnement caché : tokens de sortie × le prix de sortie. Pour DeepSeek-V4-Flash, ce prix est de $0.10 par million de tokens de sortie, et son côté sortie est moins cher que le prix de référence d'OpenRouter. Il répond aussi jusqu'à 32 768 tokens à la fois avec un contexte de 380K, donc un grand max_tokens passe. Les prix sont fixes par modèle, sans heures de pointe, et le tableau ci-dessus se recalcule à partir de la liste de prix en direct. Tous les prix sont sur la page de tarification ; la page DeepSeek contient les détails du modèle.

Voici une requête à envoyer vous-même. C'est une simple tâche de résumé, donc vous n'avez pas besoin d'un long raisonnement, et la limite laisse amplement de place :

curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
    "max_tokens": 2000,
    "messages": [
      {"role": "user", "content": "Summarize in one sentence: A token is a small piece of text that a model reads and writes, and APIs bill by the token."}
    ]
  }'

Dans la réponse, usage.completion_tokens est ce que vous payez côté sortie, et finish_reason devrait être stop. S'il indique length, la limite a coupé la réponse. Pour obtenir la clé et le premier appel : docs.

Quel effort pour quel travail#

• Un fait, un résumé d'une ligne, une étiquette. Effort le plus bas. C'est le cas du début de l'article : vous n'avez pas besoin du brouillon.
• Écriture quotidienne, courte explication, modification simple. La valeur par défaut du modèle. Ne la changez qu'après avoir vu ce que coûtent les réponses.
• Un bug délicat, un plan en plusieurs étapes, un problème de maths. high ou plus, et un grand max_tokens. Ici, la réflexion supplémentaire est le but.

En cas de doute, exécutez la même invite à deux niveaux, comparez les réponses et comparez output_tokens. Si la réponse la moins chère est aussi bonne, vous avez votre niveau.

Migrer une ancienne requête : l'erreur 400#

Un code plus ancien contrôlait la réflexion avec un budget de tokens. Sur Claude 4.7 et les modèles ultérieurs (Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1), cette forme est rejetée avec une erreur 400. Vous passez à la réflexion adaptative et réglez la profondeur avec l'effort :

// before: returns 400 on newer models
"thinking": { "type": "enabled", "budget_tokens": 8000 }

// after
"thinking": { "type": "adaptive" },
"output_config": { "effort": "medium" }

Un autre piège : sur Opus 5.5, la réflexion adaptative est toujours activée, et thinking: { "type": "disabled" } renvoie 400 à tous les niveaux d'effort. Haiku 5.5 permet de désactiver la réflexion à un effort high ou inférieur. Si vous voulez moins de réflexion sur Opus 5.5, baissez l'effort au lieu de la désactiver.

Agents et longues conversations : choisissez un niveau et gardez-le#

Si votre invite est mise en cache, changer l'effort de niveau supérieur entre les requêtes invalide les points de rupture du cache pour cette conversation. Pour une boucle d'agent ou une longue conversation, choisissez un niveau dès le départ. Certains modèles proposent un effort par message en bêta qui préserve le cache, ce qui vaut la peine d'être examiné une fois les bases en place. Les longues conversations ont un second facteur de coût, traité dans pourquoi une longue conversation coûte plus cher.

Essayez sur votre propre requête#

1. Envoyez votre vraie invite une fois et lisez usage : combien de tokens de sortie, et combien d'entre eux sont de la réflexion.
2. Baissez l'effort d'un cran et envoyez-la à nouveau. Comparez les réponses et les compteurs.
3. Réglez max_tokens sur la réponse que vous voulez plus de la place pour la réflexion, et vérifiez la raison d'arrêt.

Ensuite, mettez vos propres compteurs de tokens dans le tableau de prix en direct sur la page de tarification et vous avez une estimation mensuelle.