Tu appelles l'API Claude — l'interface d'Anthropic pour envoyer des prompts et recevoir des réponses de manière programmatique — et les tâches simples marchent nickel. Extraction, résumé, classification : Claude gère. Puis tu lui balances un truc costaud. Reviewer un pull request de 2 000 lignes. Planifier une migration de base de données. Debugger une race condition. La réponse arrive vite, confiante, et subtilement fausse. Comme un étudiant qui a survolé le cours et improvise à l'examen.

Le problème, c'est pas le modèle. Le problème, c'est que tu ne lui donnes pas de brouillon.

Pourquoi "Lis la doc" ne suffit pas

Claude a une fonctionnalité appelée extended thinking — la capacité de raisonner étape par étape en interne avant de répondre, un peu comme montrer son travail en maths sauf que le travail reste caché. Anthropic l'a introduite le 24 février 2025 avec Claude 3.7 Sonnet, et ça a sacrément évolué depuis.

La doc est complète. Elle fait aussi 4 000 mots de tableaux de paramètres, d'avis de dépréciation et de guides de migration répartis sur trois pages distinctes. La plupart des devs font l'une de ces trois choses : ignorent complètement le thinking, copient-collent une config d'un article de blog qui ciblait un ancien modèle, ou l'activent sans contrôle de coût et découvrent une facture surprise de 50 $.

Le 16 avril 2026, Anthropic a livré Claude Opus 4.7 et a cassé les trois approches. Le paramètre manuel budget_tokens qui contrôlait le coût du thinking ? Renvoie une erreur 400 maintenant. Un nouveau tokenizer gonfle le nombre de tokens jusqu'à 35 %. Et le thinking est invisible par défaut — tout en te facturant au plein tarif de 25 $ par million de tokens.

Voici comment le configurer correctement, au 27 avril 2026.

Étape 1 : Activer l'Adaptive Thinking

Sur Opus 4.7, tu utilises l'adaptive thinking — le modèle décide lui-même de l'intensité de sa réflexion selon la difficulté du problème. Plus de budgets manuels de tokens. Tu contrôles l'intensité avec un paramètre effort (un simple label comme "low", "high" ou "max") au lieu de deviner un nombre.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{
        "role": "user",
        "content": "Review this SQL migration for correctness and edge cases: ..."
    }],
)

Trois lignes ajoutées : thinking, output_config, et un max_tokens plus généreux — le plafond de tokens (unités de texte traitées par l'IA, grosso modo ¾ d'un mot anglais) que la réponse peut contenir. Les thinking tokens comptent dans ce plafond, donc mets au minimum 16 000. Anthropic recommande 32 000+ pour les tâches complexes. Si le thinking à lui seul dépasse ton max, la requête échoue — pas de réponse partielle, juste une erreur.

/faion est l'outil de prompts de Nero pour générer du code fonctionnel à partir d'une spec — colle le bloc ci-dessous et obtiens un point de départ prêt pour la prod.

/faion
Generate a Python function `call_with_thinking(prompt: str, effort: str = "high") -> str` that calls Claude Opus 4.7 with adaptive thinking using the anthropic Python SDK. Accept an effort parameter ("low", "medium", "high", "xhigh", "max"). Set max_tokens to 16000. Return the text response. Include error handling for API errors and a docstring explaining the effort levels.

Étape 2 : Choisir le bon niveau d'effort

Chaque prompt ne mérite pas une thèse de doctorat. Voici l'antisèche, basée sur les recommandations d'Anthropic et les données de production des tests de Resolve AI :

Effort Ce que ça fait Quand l'utiliser
low Saute le thinking pour les tâches triviales Classification, extraction, pipelines à haut volume
medium Raisonnement modéré, peut sauter Équilibre coût/qualité, la plupart des workflows agentiques
high Pense presque toujours en profondeur Revue de code, analyse, planification
xhigh Exploration étendue (Opus 4.7 uniquement) Coding multi-fichiers, longues chaînes agentiques
max Aucune contrainte sur le thinking Problèmes frontière, recherche, budgets illimités

La découverte clé de Resolve AI : Sonnet 4.6 à medium égale à peu près la qualité d'Opus 4.6 pour une fraction du coût. Ne fonce pas sur le plus gros modèle — choisis le bon niveau d'effort sur un modèle moins cher. L'optimisation la plus maligne, c'est souvent de ne pas payer pour Opus du tout.

Étape 3 : Streamer le thinking pour une UX en temps réel

Sans streaming, une requête à forte réflexion signifie que ton utilisateur fixe un écran mort pendant 30+ secondes. Avec le streaming, il voit le raisonnement du modèle se dérouler en live — une progression visible au lieu d'un doute existentiel sur un éventuel crash de l'app.

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": "Analyze this codebase architecture..."}],
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(f"[thinking] {event.delta.thinking}", end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

Note le "display": "summarized". Sur Opus 4.7, la valeur par défaut est "omitted" — le modèle réfléchit, tu paies les tokens, mais le texte de réflexion revient vide. Tu dois définir display explicitement si tu veux voir ce que le modèle a raisonné. Debugger un raisonnement invisible, c'est exactement aussi fun que ça en a l'air.

/faion
Generate a Python function `stream_thinking_response(prompt: str, effort: str = "high")` that calls Claude Opus 4.7 with adaptive thinking and streaming enabled via the anthropic Python SDK. Set display to "summarized". Print thinking deltas prefixed with "[thinking]" and text deltas without prefix. Set max_tokens to 32000. Handle stream cleanup properly with a context manager.

Étape 4 : Gérer le Tool Use sans casser la chaîne

Si ton intégration utilise des tools — des fonctions que le modèle peut appeler, comme interroger une base de données ou taper sur une API externe — tu dois préserver les blocs de thinking quand tu continues la conversation. Supprime-les et Claude perd son contexte de raisonnement en plein milieu.

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[your_tool],
    messages=[
        {"role": "user", "content": "What's the production error rate?"},
        {"role": "assistant", "content": [
            thinking_block,   # GARDE ÇA — le supprimer tue le contexte
            tool_use_block
        ]},
        {"role": "user", "content": [tool_result]},
    ],
)

Une contrainte qui va mordre les architectures agentiques : avec le thinking activé, tool_choice — qui contrôle si Claude doit utiliser un outil spécifique — ne supporte que "auto" ou "none". Forcer un outil spécifique renvoie une erreur.

Étape 5 : Surveiller ce que tu paies vraiment

Chaque réponse inclut un objet usage. Après avoir activé le thinking, ça devient la ligne la plus importante de ta codebase :

cost_per_mtok = 25  # Prix output Opus 4.7
output_cost = (response.usage.output_tokens / 1_000_000) * cost_per_mtok
print(f"Output tokens: {response.usage.output_tokens} (${output_cost:.4f})")

Le compteur d'output tokens inclut TOUS les thinking tokens — même les invisibles sous display: "omitted". Si ta réponse visible fait 500 tokens mais que output_tokens affiche 8 000, tu viens de payer 7 500 tokens de raisonnement que personne n'a vu. Selon la page de tarification d'Anthropic, les thinking tokens sont facturés au tarif output plein : 25 $/MTok pour Opus, 15 $/MTok pour Sonnet.

/faion
Generate a Python helper function `log_thinking_cost(response, model: str = "claude-opus-4-7")` that takes an Anthropic Messages API response object and prints a cost breakdown: input tokens, output tokens (including thinking), cache read tokens, and total estimated cost in USD. Use a dict of per-model pricing (Opus 4.7: $15 input / $25 output, Sonnet 4.6: $3 input / $15 output). Warn if output_tokens exceeds 5000 with a note about possible high thinking usage.

Les pièges qui vont te mordre

La taxe du tokenizer. Le nouveau tokenizer d'Opus 4.7 génère jusqu'à 35 % de tokens en plus pour le même texte comparé à Opus 4.6. Tes coûts augmentent sans aucun changement de code quand tu changes de modèle. Un processus de thinking qui coûtait 0,25 $ sur Opus 4.6 peut grimper à 0,34 $ sur 4.7 — même raisonnement, facture plus salée. Surveille usage avant et après le changement de modèle.

Les thinking tokens ne sont pas cachables. Le prompt caching — la fonctionnalité d'Anthropic qui réduit le coût des tokens d'entrée répétés — ne s'applique pas au contenu de thinking. Dans les boucles agentiques avec beaucoup d'appels d'outils, Claude relit les blocs de thinking des tours précédents comme input. Ça crée des coûts composés que tu ne verras pas sauf si tu suis cache_read_input_tokens séparément.

Le piège legacy. Encore sur Claude Sonnet 4.6 ou Opus 4.6 ? budget_tokens marche toujours. Passe à Opus 4.7, et ça renvoie une erreur 400 sans aucun avertissement de dépréciation — juste un fail sec. Teste avant de déployer.

Le plafond max_tokens. Les thinking tokens et les tokens de réponse partagent le même plafond max_tokens. Mets max_tokens: 4000, et si le modèle réfléchit pendant 3 800 tokens, tu obtiens une réponse de 200 tokens. Mets toujours plus haut que ce que tu penses nécessaire.

Ce que tu peux faire maintenant

Tu as deux vitesses. Pour les 80 % routiniers — extraction, formatage, Q&A simple — utilise effort: "low" ou désactive le thinking complètement. Pour les 20 % qui piquent — revue de code, planification d'architecture, analyse complexe — utilise "high" ou "xhigh" avec streaming et suivi des coûts. Lance 100 appels, vérifie les chiffres de usage, puis ajuste.

Il y a un an, chaque appel à l'API Claude tournait à la même profondeur — rapide, superficiel, une seule vitesse. Maintenant tu contrôles le curseur. Le modèle qui réfléchit 30 secondes sur un bug complexe est le même modèle qui saute le thinking sur une tâche de classification. Même endpoint, même code, trois lignes de config d'écart. Tourne le bouton.