Les paramètres d'API des modèles de raisonnement, comparés entre fournisseurs

Les modèles de raisonnement ajoutent une étape que vous ne pouvez pas voir : avant d'écrire une réponse, le modèle produit des jetons de raisonnement cachés, et ces jetons coûtent de l'argent, consomment la fenêtre de contexte et ajoutent de la latence. Chaque fournisseur vous donne un cadran pour contrôler l'ampleur de cela, mais les trois cadrans ont des noms différents, des échelles de valeurs différentes et des valeurs par défaut différentes — reasoning_effort chez OpenAI, thinking chez Anthropic, thinkingConfig chez Gemini. Bien maîtriser les modèles de raisonnement, c'est surtout comprendre ces trois réglages et un fait partagé : les jetons de raisonnement sont facturés comme des jetons de sortie même si vous ne les lisez jamais. Cet article parcourt les paramètres de chaque fournisseur, les champs d'usage qui exposent le coût caché, et là où les abstractions cessent de s'aligner.

Le modèle mental partagé

Quel que soit le fournisseur, une requête de raisonnement a la même anatomie. Vos jetons d'entrée entrent. Le modèle génère deux sortes de sortie : des jetons de raisonnement cachés et des jetons de réponse visibles. Les deux sont facturés au tarif de sortie, les deux comptent dans la fenêtre de contexte du modèle, et seuls les visibles vous reviennent (éventuellement accompagnés d'un résumé du raisonnement, jamais le raisonnement brut lui-même sur la plupart des modèles). Le cadran que chaque fournisseur expose change le nombre de jetons cachés que le modèle est prêt à dépenser. Montez-le pour les problèmes difficiles et les boucles agentiques à plusieurs étapes ; baissez-le pour les tâches superficielles sensibles à la latence. Tout ce qui suit est une variation sur ce thème.

OpenAI : reasoning_effort et l'objet reasoning

Sur les modèles de raisonnement d'OpenAI, vous définissez l'effort. Chat Completions prend une chaîne reasoning_effort de premier niveau ; l'API Responses prend un objet reasoning dont le champ effort fait le même travail et ménage de la place pour un résumé et des contrôles de contexte.

from openai import OpenAI
client = OpenAI(base_url="https://your-gateway.example.com/v1", api_key="AVE_GATEWAY_API_KEY")

# Responses API
resp = client.responses.create(
    model="gpt-5.6",
    input="Prove there are infinitely many primes p with p mod 4 == 3.",
    reasoning={"effort": "high", "summary": "auto"},
)

Les valeurs d'effort dépendent du modèle et peuvent inclure none, minimal, low, medium, high et xhigh ; la valeur par défaut varie selon le modèle. Un effort plus faible privilégie la vitesse et moins de jetons, un effort plus élevé produit une sortie plus approfondie à un coût plus élevé. Le travail caché est mesuré : les jetons de raisonnement apparaissent dans usage sous output_tokens_details comme reasoning_tokens, de sorte que vous pouvez observer la dépense invisible même si les jetons eux-mêmes sont retenus. Pour voir pourquoi le modèle a conclu quelque chose, demandez un résumé (summary: "auto" ou "detailed"), qui renvoie une trace de raisonnement résumée dans l'élément de sortie reasoning — vous devez y consentir ; ce n'est pas inclus par défaut.

Deux fonctionnalités comptent pour les configurations sans état et agentiques. Pour un fonctionnement à rétention zéro, envoyez store: false et ajoutez reasoning.encrypted_content au tableau include ; l'API renvoie un raisonnement chiffré que vous repassez au tour suivant pour préserver la continuité sans que le serveur ne stocke rien. Et reasoning.context (auto, current_turn ou all_turns) contrôle quels éléments de raisonnement antérieurs le modèle peut mobiliser à travers une conversation chaînée.

Le paramètre que vous ne devez pas oublier est max_output_tokens. Il plafonne le total des jetons générés — raisonnement plus réponse visible — si bien que si vous le fixez trop bas, le budget peut être entièrement consommé par le raisonnement caché et vous recevez un status de incomplete (avec incomplete_details citant max_output_tokens) et aucun texte visible, tout en payant quand même pour les jetons d'entrée et de raisonnement. OpenAI recommande de réserver une marge généreuse (de l'ordre de dizaines de milliers de jetons) pour le raisonnement plus la sortie quand vous débutez. Budgétiser cette marge est la même discipline décrite dans la gestion de la fenêtre de contexte des LLM.

Anthropic : de budget_tokens au raisonnement adaptatif

Le raisonnement étendu d'Anthropic a historiquement utilisé un budget de jetons explicite. Vous l'activez avec un objet thinking de type: "enabled" et un plafond budget_tokens :

import anthropic
client = anthropic.Anthropic(base_url="https://your-gateway.example.com", api_key="AVE_GATEWAY_API_KEY")

msg = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "Are there infinitely many primes p with p mod 4 == 3?"}],
)

Trois règles gouvernent budget_tokens. Il fixe le maximum de jetons pour le raisonnement interne et doit être inférieur à max_tokens (sauf lorsque le raisonnement entrelacé avec des outils permet à la limite de devenir la fenêtre de contexte entière). Le modèle peut ne pas utiliser tout le budget, surtout aux grandes valeurs. Et le raisonnement apparaît comme des blocs de contenu thinking — chacun portant un texte thinking et une signature — avant les blocs text ; vous êtes facturé pour la totalité des jetons de raisonnement générés, pas pour le résumé plus court, si bien que le compte de sortie facturé ne correspondra pas à ce que vous voyez visiblement.

Il y a une division de version importante à anticiper. budget_tokens est en train d'être retiré : il est déprécié sur certains modèles actuels et renvoie un 400 sur les plus récents (par exemple la génération Opus 4.8/4.7 et Sonnet 5), qui utilisent à la place le raisonnement adaptatif — un objet thinking de type: "adaptive" associé à un réglage d'effort, rapprochant conceptuellement Anthropic du cadran d'effort d'OpenAI. Lorsque vous construisez, branchez sur le modèle : envoyez budget_tokens aux modèles qui l'acceptent encore et la forme adaptative/effort à ceux qui l'exigent. Une passerelle peut masquer une partie de ceci, comme le montre la section suivante.

Une règle d'usage d'outils est non négociable : pendant une boucle d'outils, vous devez repasser les blocs thinking du modèle sans modification dans le message assistant suivant, sinon l'API rejette la requête avec un 400. Les blocs encodent le raisonnement qui a mené à l'appel d'outil, et les réordonner ou les modifier casse la continuité. Cela reflète le conseil d'OpenAI de renvoyer les éléments de raisonnement avec les appels de fonction, et c'est pourquoi l'appel d'outils portable entre fournisseurs traite la préservation des blocs de raisonnement comme partie intégrante d'une boucle d'outils correcte.

Gemini : thinkingConfig et thinkingBudget

Gemini contrôle le raisonnement via un thinkingConfig à l'intérieur de generationConfig. Le champ clé est thinkingBudget, une allocation de jetons pour la réflexion, avec deux valeurs spéciales : -1 laisse le modèle décider dynamiquement, et (sur les modèles qui permettent de le désactiver) 0 désactive la réflexion. Un drapeau includeThoughts demande à l'API de renvoyer un résumé de la réflexion. Le raisonnement consommé apparaît dans usageMetadata comme un compte de jetons de réflexion (thoughts), là encore facturé comme sortie.

from google import genai
from google.genai import types

client = genai.Client()
resp = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Are there infinitely many primes p with p mod 4 == 3?",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_budget=-1, include_thoughts=True),
    ),
)

Quels modèles vous laissent désactiver la réflexion, et les plages de budget exactes, varient selon le niveau de modèle — consultez la page du modèle plutôt que de supposer qu'une valeur se reporte d'une génération à l'autre.

Ce qu'une passerelle normalise, et où elle s'arrête

Derrière un seul point de terminaison compatible OpenAI, une passerelle transmet les paramètres de raisonnement de chaque fournisseur à l'amont qui les comprend : reasoning_effort et l'objet reasoning à OpenAI, thinking à Anthropic, thinkingConfig à Gemini. Elle replie aussi les trois différents comptes de jetons cachés dans une vue d'usage unifiée, de sorte que le coût de sortie réel d'une requête de raisonnement soit visible dans vos journaux quel que soit le fournisseur qui l'a servie.

Cette passerelle offre en outre une commodité qu'il vaut la peine de connaître : elle peut parser un suffixe d'effort sur le nom du modèle et le traduire dans le paramètre de raisonnement propre au fournisseur. Ajouter -high, -medium, -low, -minimal, -xhigh ou -max à un identifiant de modèle (par exemple claude-opus-4-8-high ou une variante -thinking) permet à un client qui ne peut définir qu'une chaîne de modèle de choisir malgré tout un niveau d'effort, et la passerelle mappe ce suffixe vers le bon réglage pour le fournisseur cible. Les variantes modèle/effort enregistrées et leurs tarifs par modèle sont publiés sur la page publique de tarification.

Soyez explicite sur les limites, car les abstractions ne s'alignent véritablement pas :

• Les échelles sont différentes. L'effort d'OpenAI est une énumération, le budget_tokens hérité d'Anthropic est un compte de jetons absolu, et le thinkingBudget de Gemini est un compte de jetons avec des valeurs sentinelles. « Effort élevé » et « 10 000 jetons de budget » ne sont pas des traductions l'un de l'autre ; mapper l'un vers l'autre est une heuristique, pas une équivalence.
• Les valeurs par défaut diffèrent. Certains modèles raisonnent par défaut, d'autres non, et l'effort par défaut est spécifique au modèle. Ne supposez pas que le silence signifie « pas de raisonnement ».
• La couverture des fonctionnalités diffère. La continuité du raisonnement chiffré, les résumés de réflexion et la désactivation de la réflexion sont pris en charge de façon inégale entre les fournisseurs. Une passerelle peut transmettre un champ, mais elle ne peut pas faire honorer par un fournisseur une capacité qu'il n'offre pas.

Considérez la passerelle comme la couche qui vous donne une seule vue de facturation et un seul chemin de passthrough, et gardez la logique spécifique au fournisseur là où existe un véritable écart de capacité.

Valeurs par défaut pratiques

Quelques règles de départ font gagner de l'argent et de la latence :

1. Adaptez l'effort à la profondeur de la tâche, pas à son importance. Une extraction difficile a besoin de plus de raisonnement qu'une longue mais superficielle synthèse. L'effort concerne la structure du problème, pas les enjeux.
2. Réservez toujours une marge de sortie. Avec tout modèle de raisonnement, fixez le plafond de sortie maximal assez haut pour que le raisonnement caché ne puisse pas affamer la réponse visible, sinon vous paierez pour le raisonnement et ne recevrez rien.
3. Mesurez les jetons cachés. Observez reasoning_tokens / les jetons de réflexion dans vos journaux d'usage ; une tâche dont les jetons de raisonnement écrasent ses jetons de réponse est candidate à un effort plus faible ou à un modèle sans raisonnement, une décision traitée dans choisir le bon modèle LLM.

FAQ

Les jetons de raisonnement sont-ils facturés même si je ne les vois jamais ?

Oui. Les jetons de raisonnement cachés sont facturés au tarif des jetons de sortie chez les trois fournisseurs et occupent aussi la fenêtre de contexte. C'est pourquoi le compte de sortie facturé est plus grand que ce que la réponse visible laisserait supposer, et pourquoi observer le champ des jetons de raisonnement dans vos journaux d'usage importe — c'est une dépense réelle que vous ne pouvez pas voir dans le corps de la réponse.

Pourquoi ai-je obtenu une réponse vide ou incomplète d'un modèle de raisonnement ?

Généralement, le plafond de sortie était trop bas et le raisonnement a consommé tout le budget. OpenAI renvoie un status de incomplete citant max_output_tokens ; Anthropic exige que budget_tokens soit inférieur à max_tokens. Augmentez la limite de sortie totale pour que le raisonnement caché ne puisse pas affamer la réponse visible, et réservez une marge généreuse sur les routes de raisonnement.

Le budget_tokens d'Anthropic est-il la même chose que le reasoning_effort d'OpenAI ?

Ils servent le même but mais ne sont pas équivalents. reasoning_effort est une énumération (low/medium/high et valeurs apparentées) ; budget_tokens est un compte de jetons absolu. Sur les modèles les plus récents d'Anthropic, budget_tokens n'est pas pris en charge et le raisonnement adaptatif avec un réglage d'effort le remplace. Une passerelle peut mapper une étiquette d'effort sur le paramètre d'un fournisseur, mais le mappage est approximatif, pas une traduction un-à-un.

Comment définir un niveau de raisonnement si mon client ne peut envoyer qu'un nom de modèle ?

Utilisez le suffixe d'effort de la passerelle. Ajoutez -high, -medium, -low, -minimal, -xhigh ou -max à l'identifiant du modèle et la passerelle le parse et applique le paramètre de raisonnement correspondant pour le fournisseur cible. Cela permet à des clients légers de choisir un niveau d'effort sans envoyer eux-mêmes le champ spécifique au fournisseur.

Trouvez le coude d'effort sur votre tâche

Exécutez le même prompt difficile trois fois, avec un effort faible, moyen et élevé, à travers votre passerelle, et relevez à chaque fois deux valeurs dans vos journaux d'usage : les jetons de raisonnement et la qualité de la réponse selon votre propre grille. Vous trouverez généralement un coude à partir duquel davantage d'effort n'améliore plus la réponse mais continue de consommer des jetons. Fixez votre route juste sous ce coude : cette seule mesure, sur votre tâche, vaut mieux que n'importe quelle valeur par défaut d'un fournisseur.

Références

• OpenAI : Reasoning models
• Anthropic : Extended thinking
• Google Gemini : Thinking
• Référence de l'API OpenAI