Effort

Le paramètre effort vous permet de contrôler le nombre de tokens que Claude dépense pour répondre aux requêtes. Vous pouvez arbitrer entre l'exhaustivité des réponses et l'efficacité en tokens avec un seul modèle. Le paramètre effort de niveau supérieur est disponible sur tous les modèles pris en charge, sans en-tête bêta requis. L'effort par message est en bêta.

Définir le niveau d'effort

Définissez output_config.effort sur la requête. L'exemple suivant exécute une requête avec un effort medium et affiche le texte de la réponse.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Fonctionnement de l'effort

La plupart des modèles Claude utilisent par défaut un effort élevé (high), en dépensant autant de tokens que nécessaire pour obtenir d'excellents résultats ; Claude Opus 5.5 et Claude Haiku 5.5 utilisent par défaut un effort moyen (medium). Vous pouvez augmenter le niveau d'effort jusqu'à max pour obtenir la capacité la plus élevée possible, ou le réduire pour être plus économe en tokens, en optimisant la vitesse et le coût tout en acceptant une certaine réduction des capacités.

Le paramètre effort affecte tous les tokens de la réponse, notamment :

• Les réponses textuelles et les explications
• Les appels d'outils et les arguments de fonctions
• La réflexion (lorsqu'elle est active)

Comme l'effort s'applique à chaque token de sortie, il fonctionne que la réflexion soit activée ou non. Un effort plus faible signifie également des appels d'outils moins nombreux et plus concis.

Niveaux d'effort

Tous les modèles qui prennent en charge max ne prennent pas nécessairement en charge xhigh.

Les recommandations par modèle qui suivent prévalent sur ce tableau lorsqu'elles diffèrent.

Niveaux d'effort recommandés pour Claude Fable 5.1

Claude Fable 5.1 prend en charge les cinq niveaux d'effort. Commencez par high, la valeur par défaut. Passez à xhigh ou max pour les travaux agentiques et de codage les plus sensibles à la capacité, et descendez à medium ou low pour les travaux routiniers ou sensibles à la latence une fois que vos évaluations montrent que la qualité se maintient. À high et au-delà, définissez une valeur élevée pour max_tokens. Il s'agit d'une limite stricte sur la sortie totale (réflexion plus texte de réponse). Les mêmes recommandations s'appliquent à Claude Mythos 5.1. Consultez Prompting de Claude Fable 5.1.

Claude Fable 5.1 prend également en charge le changement d'effort en cours de conversation avec un output_config par message, ce qui préserve le cache de prompts.

Niveaux d'effort recommandés pour Claude Fable 5

L'effort est le contrôle principal pour arbitrer entre intelligence, latence et coût sur Claude Fable 5. Commencez par high, la valeur par défaut, pour la plupart des tâches, utilisez xhigh pour les charges de travail les plus sensibles à la capacité, et descendez à medium ou low pour les travaux routiniers. Les réglages d'effort inférieurs sur Claude Fable 5 restent performants et dépassent souvent les performances de xhigh sur les modèles précédents. À high et xhigh, définissez une valeur élevée pour max_tokens. Il s'agit d'une limite stricte sur la sortie totale (réflexion plus texte de réponse). Consultez Contrôle des coûts.

Réduisez l'effort si une tâche aboutit mais prend plus de temps que nécessaire, ou si vous souhaitez un style de travail plus rapide et plus interactif. Les mêmes recommandations s'appliquent à Claude Mythos 5. Pour des conseils plus complets, consultez Prompting de Claude Fable 5.

Niveaux d'effort recommandés pour Claude Opus 5.5

Claude Opus 5.5 prend en charge les cinq niveaux d'effort, et medium est la valeur par défaut (Claude Opus 5 et les modèles Opus antérieurs utilisent high par défaut, de sorte qu'une requête qui omet effort s'exécute un niveau plus bas que sur Claude Opus 5). La réflexion adaptative est toujours active et ne peut pas être désactivée ; l'effort est donc le principal levier pour contrôler la quantité de raisonnement du modèle et le coût d'une requête. Effectuez un balayage des niveaux d'effort sur vos propres évaluations plutôt que de reprendre les réglages d'un modèle antérieur, et définissez une valeur élevée pour max_tokens aux niveaux supérieurs : il s'agit d'une limite stricte sur la sortie totale (réflexion plus texte de réponse). Les requêtes qui définissent thinking: {"type": "disabled"} renvoient une erreur 400 à tous les niveaux d'effort. Claude Opus 5.5 prend également en charge le changement d'effort en cours de conversation avec un output_config par message, ce qui préserve le cache de prompts. Consultez Rédiger des prompts pour Claude Opus 5.5.

Niveaux d'effort recommandés pour Claude Opus 5

Claude Opus 5 prend en charge les cinq niveaux d'effort. Commencez par high, la valeur par défaut, et ajustez en fonction de vos évaluations : passez à xhigh pour les travaux de codage et agentiques exigeants, ou à max lorsqu'une tâche justifie une dépense de tokens sans contrainte, et utilisez largement low et medium comme principal contrôle du coût en tokens et du temps de réponse partout où vos évaluations montrent que la qualité se maintient. Si vous avez repris les réglages d'effort d'un modèle antérieur, effectuez un nouveau balayage des niveaux d'effort sur vos évaluations plutôt que de les réutiliser.

L'effort contrôle le volume de réflexion, et non la longueur visible de la réponse : sur Claude Opus 5, modifier l'effort ne raccourcit pas les réponses de manière fiable ; indiquez plutôt la longueur souhaitée dans le prompt.

La valeur par défaut de l'API est high. Définissez effort explicitement pour utiliser un autre niveau. La valeur que vous transmettez remplace la valeur par défaut.

Sur Claude Opus 5, la réflexion ne peut pas être désactivée avec un effort xhigh ou max : les requêtes qui définissent thinking: {"type": "disabled"} à ces niveaux renvoient une erreur 400. Consultez Effort avec la réflexion.

Lorsque vous exécutez Claude Opus 5 avec un effort xhigh ou max, définissez une valeur élevée pour max_tokens afin que le modèle dispose de la marge nécessaire pour réfléchir et agir à travers les sous-agents et les appels d'outils. Commencer à 64k tokens et ajuster à partir de là constitue une valeur par défaut raisonnable.

Claude Opus 5 prend également en charge le changement d'effort en cours de conversation avec un output_config par message, ce qui préserve le cache des prompts. L'effort par message n'est pas disponible pour Claude Opus 5 sur Amazon Bedrock.

Niveaux d'effort recommandés pour Claude Opus 4.8

Les conseils pour Claude Opus 4.7 s'appliquent également à Claude Opus 4.8. Commencez par xhigh pour les cas d'utilisation de codage et agentiques, utilisez high pour la plupart des autres charges de travail sensibles à l'intelligence, et ne descendez à medium ou low que lorsque vous avez mesuré que le niveau inférieur maintient la qualité sur vos évaluations.

La valeur par défaut de l'API est high. Définissez effort explicitement pour utiliser un niveau différent. La valeur que vous transmettez remplace la valeur par défaut.

Lorsque vous exécutez Claude Opus 4.8 avec un effort xhigh ou max, définissez une valeur élevée pour max_tokens afin que le modèle dispose de la marge nécessaire pour réfléchir et agir à travers les sous-agents et les appels d'outils. Commencer à 64k tokens et ajuster à partir de là constitue une valeur par défaut raisonnable.

Niveaux d'effort recommandés pour Claude Opus 4.7

Commencez par xhigh pour les cas d'utilisation de codage et agentiques, et utilisez high comme minimum pour la plupart des charges de travail sensibles à l'intelligence. Descendez à medium pour les charges de travail sensibles aux coûts, ou montez à max uniquement lorsque vos évaluations montrent une marge de progression mesurable par rapport à xhigh.

La valeur par défaut de l'API est high. Pour utiliser xhigh, définissez effort explicitement. La valeur que vous transmettez remplace la valeur par défaut.

Claude Opus 4.7 respecte également les niveaux d'effort plus strictement que Claude Opus 4.6, en particulier avec low et medium. Aux niveaux d'effort plus faibles, le modèle limite son travail à ce qui a été demandé plutôt que d'en faire plus que nécessaire. Si vous observez un raisonnement superficiel sur des problèmes complexes avec Claude Opus 4.7, augmentez l'effort plutôt que de contourner le problème par le prompt. Si vous devez maintenir un effort faible pour des raisons de latence, ajoutez des consignes ciblées comme « This task involves multistep reasoning. Think carefully before responding. »

Lorsque vous exécutez Claude Opus 4.7 avec un effort xhigh ou max, définissez une valeur élevée pour max_tokens afin que le modèle dispose de la marge nécessaire pour réfléchir et agir à travers les sous-agents et les appels d'outils. Commencer à 64k tokens et ajuster à partir de là constitue une valeur par défaut raisonnable.

Niveaux d'effort recommandés pour Claude Sonnet 5.5

Claude Sonnet 5.5 prend en charge les cinq niveaux d'effort, et high est la valeur par défaut sur la Claude API. Ses niveaux sont recalibrés : un niveau donné ne produit donc pas la même quantité de réflexion que le même niveau sur Claude Sonnet 5. Effectuez un nouveau balayage des niveaux d'effort sur vos évaluations plutôt que de reprendre le réglage que vous utilisiez sur Claude Sonnet 5. Commencez par high, sauf si votre charge de travail est agentique ou sensible à la latence. Pour le codage agentique et l'utilisation d'outils en plusieurs étapes, commencez par medium pour les tâches bien spécifiées et passez à high pour les tâches plus difficiles ou plus longues. Pour le chat et les autres travaux sensibles à la latence, commencez par medium ou low. N'utilisez xhigh ou max que lorsque vos évaluations montrent un gain de qualité. Définissez max_tokens avec une marge suffisante pour la réflexion et la réponse. La réflexion est comptabilisée dans max_tokens même lorsque le contenu de la réflexion n'est pas renvoyé. Pour le codage agentique, définissez max_tokens sur 128 000, le maximum du modèle, et utilisez le streaming pour la réponse.

Pour désactiver la réflexion préalable, envoyez thinking: {"type": "between_tools"} au lieu de "disabled". Il s'agit du réglage de réflexion le plus bas sur Claude Sonnet 5.5, et il fonctionne avec un effort low, medium et high. Avec xhigh ou max, une requête qui l'utilise renvoie une erreur 400 ; utilisez donc la réflexion adaptative à ces niveaux : omettez le champ thinking ou envoyez thinking: {"type": "adaptive"}. Consultez Exécution sans réflexion préalable.

Claude Sonnet 5.5 prend également en charge le changement d'effort en cours de conversation avec un output_config par message, ce qui préserve le cache des prompts. Avec between_tools, l'effort ne peut pas changer en cours de conversation : un output_config.effort par message qui diffère du niveau en vigueur renvoie une erreur 400. Pour faire varier l'effort à chaque tour, utilisez la réflexion adaptative. Consultez Rédiger des prompts pour Claude Sonnet 5.5.

Niveaux d'effort recommandés pour Claude Sonnet 5

Claude Sonnet 5 utilise par défaut l'effort high sur la Claude API et Claude Code.

• Effort high (par défaut) : Adapté au raisonnement complexe, au codage et aux tâches agentiques où la qualité importe plus que la vitesse ou le coût.
• Effort xhigh : Pour les tâches de codage et agentiques les plus difficiles. Consultez Prompting de Claude Sonnet 5.
• Effort medium : Niveau inférieur économique par rapport à la valeur par défaut. Comparable à Claude Sonnet 4.6 avec un effort high.
• Effort low : Pour les charges de travail à volume élevé ou sensibles à la latence. Adapté au chat et aux cas d'utilisation hors codage où un délai de réponse plus rapide est prioritaire.
• Effort max : Pour les tâches nécessitant la capacité la plus élevée possible sans contrainte sur la dépense de tokens.

Niveaux d'effort recommandés pour Claude Sonnet 4.6

Sonnet 4.6 utilise par défaut un effort high. Définissez explicitement l'effort lorsque vous utilisez Sonnet 4.6 afin d'éviter une latence inattendue :

• Effort medium (valeur par défaut recommandée) : Meilleur équilibre entre vitesse, coût et performances pour la plupart des applications. Adapté au codage agentique, aux flux de travail faisant un usage intensif d'outils et à la génération de code.
• Effort low : Pour les charges de travail à volume élevé ou sensibles à la latence. Adapté au chat et aux cas d'utilisation hors codage où un délai de réponse plus rapide est prioritaire.
• Effort high : Pour le raisonnement complexe et les tâches où la qualité compte davantage que la vitesse ou le coût.
• Effort max : Pour les tâches nécessitant la capacité la plus élevée possible, sans aucune contrainte sur la dépense de tokens.

Niveaux d'effort recommandés pour Claude Haiku 5.5

Claude Haiku 5.5 prend en charge les cinq niveaux d'effort, et medium est la valeur par défaut sur la Claude API et dans Claude Code. L'effort est le principal contrôle de la quantité de réflexion du modèle, et donc de la qualité, de la latence et du coût. Commencez par medium pour la plupart des travaux, y compris le codage agentique. Utilisez low, le niveau le moins cher et le plus rapide, pour le chat, les tâches courtes impliquant des outils et les requêtes simples à volume élevé. Dans les longs prompts d'agent, le modèle est plus susceptible de sauter une recherche, de s'arrêter prématurément ou d'omettre une vérification avec low. Utilisez high pour le travail intellectuel, les tâches d'agent plus longues et le respect strict des instructions. N'utilisez xhigh ou max que lorsque vos évaluations montrent un gain de qualité, et comparez-les avec Claude Sonnet 5.5 en termes de performances, de coût et de vitesse. La réflexion est activée par défaut et est comptabilisée dans max_tokens ; prévoyez donc une marge suffisante. Consultez Rédiger des prompts pour Claude Haiku 5.5.

Pour obtenir moins de réflexion, réduisez le niveau d'effort. Vous pouvez également envoyer thinking: {"type": "disabled"} avec un effort high ou inférieur. Avec xhigh ou max, cela renvoie une erreur 400 ; utilisez donc la réflexion adaptative à ces niveaux : omettez le champ thinking ou envoyez thinking: {"type": "adaptive"}.

Sur la Claude API et Google Cloud, Claude Haiku 5.5 prend également en charge le changement d'effort en cours de conversation avec un output_config par message, ce qui préserve le cache des prompts. Avec thinking: {"type": "disabled"}, l'effort ne peut pas changer en cours de conversation : un output_config.effort par message qui diffère du niveau en vigueur renvoie une erreur 400. Pour faire varier l'effort à chaque tour, utilisez la réflexion adaptative.

Effort avec l'utilisation d'outils

Lors de l'« tool use » (utilisation d'outils), le paramètre effort affecte à la fois les explications entourant les appels d'outils et les appels d'outils eux-mêmes. Les niveaux d'effort inférieurs ont tendance à :

• Combiner plusieurs opérations en moins d'appels d'outils
• Effectuer moins d'appels d'outils
• Passer directement à l'action sans préambule
• Utiliser des messages de confirmation concis après achèvement

Les niveaux d'effort supérieurs peuvent :

• Effectuer davantage d'appels d'outils
• Expliquer le plan avant d'agir
• Fournir des résumés détaillés des modifications
• Inclure des commentaires de code plus complets

Effort avec la réflexion

Le paramètre thinking contrôle si Claude réfléchit dans des blocs de réflexion avant de répondre ; le paramètre effort contrôle la quantité de travail que Claude consacre à l'ensemble de la réponse, ce qui, en mode adaptatif, inclut la fréquence et la profondeur de sa réflexion. Ne passez pas adaptive comme valeur de effort : adaptive est un mode de réflexion, et non un niveau d'effort.

Aux niveaux d'effort supérieurs, Claude réfléchit plus volontiers et plus longuement. Dans une boucle d'utilisation d'outils, les requêtes de suivi qui ne font que traiter des résultats d'outils peuvent toujours ignorer la réflexion, quel que soit le niveau. Aux niveaux inférieurs, Claude peut ignorer entièrement la réflexion pour les problèmes plus simples. Consultez Réflexion et effort pour des conseils complets sur la façon dont ces deux contrôles fonctionnent ensemble.

Sur Claude Opus 4.5, le seul modèle à « extended thinking » (réflexion étendue) uniquement qui prend en charge l'effort, celui-ci fonctionne conjointement avec budget_tokens : définissez le niveau d'effort pour votre tâche, puis définissez le budget de tokens de réflexion en fonction de la profondeur de raisonnement requise par la tâche.

Pour la disponibilité de la réflexion par modèle, consultez le tableau de configuration par modèle. L'effort fonctionne avec ou sans réflexion. Consultez Fonctionnement de l'effort.

Changer l'effort en cours de conversation

Vous pouvez exécuter les tours ultérieurs d'une conversation à un niveau d'effort différent de deux manières. Sur Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 et Claude Haiku 5.5, utilisez un changement d'effort par message, qui conserve le cache des prompts. Sur les autres modèles, définissez une nouvelle valeur de niveau supérieur dans la requête suivante, ce qui réinitialise le cache.

Effort par message (bêta)

L'effort par message est en bêta. Sur la Claude API et Google Cloud, il est disponible sur Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 et Claude Haiku 5.5. Sur Amazon Bedrock, il est disponible sur Claude Fable 5.1, Claude Mythos 5.1 et Claude Opus 5.5. Il nécessite l'en-tête bêta mid-conversation-output-config-2026-07-01. Avec l'API InvokeModel d'Amazon Bedrock, il est disponible sur Claude Fable 5.1 et Claude Opus 5.5, et vous envoyez plutôt cette valeur dans le tableau anthropic_beta du corps de la requête.

Sans la valeur bêta, un output_config par message renvoie une erreur 400 : messages.N.output_config: Extra inputs are not permitted, où N est l'index du message system dans messages. Avec la valeur bêta, les modèles sans effort par message, y compris Claude Fable 5, renvoient une erreur 400 : output_config.effort requires a model that supports per-turn effort; this model does not. Sur Amazon Bedrock, ces modèles ainsi que Claude Opus 5 renvoient plutôt l'erreur Extra inputs are not permitted. Sur Claude Sonnet 5.5 avec thinking: {"type": "between_tools"} et sur Claude Haiku 5.5 avec thinking: {"type": "disabled"}, l'effort ne peut pas changer en cours de conversation : un output_config.effort par message qui diffère du niveau en vigueur renvoie une erreur 400. Pour faire varier l'effort à chaque tour, utilisez la réflexion adaptative.

Ajoutez un message role: "system" avec un content vide et le nouveau niveau dans output_config.effort. Le nouveau niveau prend effet à partir du tour user suivant et reste en vigueur jusqu'à ce qu'un message ultérieur le modifie. Tout ce qui précède ce message reste inchangé, de sorte que le préfixe mis en cache correspond toujours.

L'exemple suivant commence avec high, puis descend à low pour une question de suivi routinière :

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5-1",
    max_tokens=4096,
    output_config={"effort": "high"},
    messages=[
        {
            "role": "user",
            "content": "Plan a migration from SQLite to PostgreSQL in three short steps.",
        },
        {
            "role": "assistant",
            "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.",
        },
        # Message système d'effort uniquement : le nouveau niveau s'applique à partir du prochain tour utilisateur.
        {"role": "system", "content": [], "output_config": {"effort": "low"}},
        {"role": "user", "content": "Summarize the plan in one sentence."},
    ],
    betas=["mid-conversation-output-config-2026-07-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Un message système ne contenant que l'effort ne comporte aucun texte ; les règles de placement des messages système en cours de conversation ne s'appliquent donc pas. Il peut apparaître n'importe où dans messages, y compris en tant que première entrée ou entre un tour assistant et le tour user suivant. Les valeurs sont les noms des niveaux (low, medium, high, xhigh et max).

Sur Claude Fable 5.1, privilégiez cette forme plutôt que de modifier la valeur de niveau supérieur entre les requêtes. Un changement de niveau supérieur réinitialise le cache et oriente également le modèle de manière moins fiable : ses réponses antérieures ont été rédigées au niveau précédent, et il a tendance à rester cohérent avec elles.

Effort de niveau supérieur sur la requête suivante

Le paramètre output_config.effort de niveau supérieur s'applique à l'ensemble de la requête. Pour exécuter une partie ultérieure d'une conversation à un niveau différent, définissez la nouvelle valeur sur la requête suivante. Comme l'effort de niveau supérieur façonne le prompt rendu, le modifier entre les requêtes ne préserve pas les préfixes mis en cache des tours précédents. Si vous comptez sur la mise en cache des prompts tout au long d'une longue session et que votre modèle ne prend pas en charge l'effort par message, choisissez un niveau d'effort au départ et maintenez-le constant.

Bonnes pratiques

1. Définissez l'effort explicitement : L'API utilise high par défaut (medium sur Claude Opus 5.5 et Claude Haiku 5.5), mais le bon point de départ dépend de votre modèle et de votre charge de travail.
2. Utilisez low pour les tâches sensibles à la vitesse ou simples : Lorsque la latence compte ou que les tâches sont simples, un effort faible peut réduire considérablement les temps de réponse et les coûts.
3. Testez votre cas d'utilisation : L'impact des niveaux d'effort varie selon le type de tâche. Évaluez les performances sur vos cas d'utilisation spécifiques avant le déploiement.
4. Envisagez un effort dynamique : Ajustez l'effort en fonction de la complexité de la tâche. Les requêtes simples peuvent justifier un effort faible, tandis que le codage agentique et le raisonnement complexe bénéficient d'un effort élevé. Consultez le point suivant avant de le faire varier au sein d'une même conversation.
5. Maintenez l'effort de niveau supérieur constant dans les conversations mises en cache : Modifier la valeur d'effort de niveau supérieur entre les requêtes invalide la mise en cache des prompts ; faites-la donc varier d'une charge de travail à l'autre plutôt qu'au sein d'une conversation qui repose sur des succès de cache. Sur les modèles qui le prennent en charge, utilisez plutôt un changement d'effort par message, qui préserve le cache. Consultez Réflexion et mise en cache des prompts.

Étapes suivantes

Compatibility