Claude Opus 5 a été lancé le 24 juillet 2026, et Anthropic oriente désormais les développeurs vers celui-ci en premier : la documentation indique que si vous ne savez pas quel modèle utiliser, commencez par Claude Opus 5. L'ID du modèle API est la chaîne exacte `claude-opus-5`, sans suffixe de date.
Ce guide vous accompagne sur l'ensemble du cheminement : obtenir une clé, envoyer une première requête, le streaming, l'utilisation d'outils, la pensée adaptative, le paramètre `effort`, et la lecture de l'objet `usage` pour confirmer que votre cache de prompt fonctionne. Chaque requête ici est du pur HTTP avec JSON en entrée et JSON en sortie, vous pouvez donc la construire et la déboguer dans Apidog avant de l'intégrer à votre code d'application.
Deux changements par rapport à Opus 4.8 vous poseront problème dès le premier appel, ils sont donc présentés avant tout le reste. Si vous migrez un service existant plutôt que de repartir de zéro, lisez le guide complet de migration d'Opus 4.8 vers Opus 5 en parallèle de celui-ci.
Avant votre premier appel : deux changements majeurs
1. La réflexion est activée par défaut. Sur Opus 4.8, une requête sans champ `thinking` s'exécutait sans aucune réflexion. Sur Opus 5, la même requête s'exécute avec une pensée adaptative. `max_tokens` est toujours une limite stricte sur les jetons de réflexion et les jetons de réponse combinés, de sorte qu'un corps de requête que vous avez copié d'une intégration 4.8 fonctionnelle peut désormais être tronqué en cours de réponse. Si votre `max_tokens` était étroitement ajusté à la longueur de sortie attendue, augmentez-le.
2. La désactivation de la réflexion limite votre niveau d'effort. L'envoi de `thinking: {"type": "disabled"}` avec un effort de `xhigh` ou `max` renvoie une erreur 400. Anthropic applique cette règle par requête, de sorte que l'échec est immédiat plutôt qu'une dégradation silencieuse. La solution consiste à choisir : soit maintenir la réflexion activée et réduire l'effort pour contrôler les coûts, soit maintenir la réflexion désactivée et limiter l'effort à `high`.
Le conseil d'Anthropic est la première option. Lorsque la réflexion est désactivée, Opus 5 écrit occasionnellement les appels d'outils en texte brut (ils ne s'exécutent jamais, et le texte divulgué pollue les tours suivants dans une boucle d'agent) et parfois des balises `<thinking>` apparaissent dans la sortie visible. Maintenir la réflexion activée et réduire l'effort permet d'éviter ces deux problèmes.
Ces deux changements sont documentés dans le guide de migration de modèle d'Anthropic.
Étape 1 : Obtenir une clé API
Connectez-vous à la plateforme développeur Claude, ouvrez la section des clés API de vos paramètres d'organisation et créez une clé. Copiez-la une seule fois ; vous ne pourrez pas la relire plus tard.
Stockez-la dans une variable d'environnement plutôt que de la coller directement dans le code :
export ANTHROPIC_API_KEY="sk-ant-..."
Si vous testez dans un client GUI, placez également la clé dans une variable d'environnement. Dans Apidog, cela signifie créer un environnement (Local, Staging, Production) avec une variable `ANTHROPIC_API_KEY`, puis référencer `{{ANTHROPIC_API_KEY}}` dans l'en-tête. Vos requêtes sauvegardées restent partageables avec l'équipe et le secret n'atterrit jamais dans une exportation de collection.
Vous devez également ajouter des crédits de facturation avant que les requêtes ne réussissent. Les tarifs pour Opus 5 sont de 5 $ par million de jetons d'entrée et de 25 $ par million de jetons de sortie, les mêmes qu'Opus 4.8, et la répartition complète des prix couvre les tarifs du caching, du batch et du mode rapide.
Étape 2 : Envoyer votre première requête
Le point de terminaison est `POST https://api.anthropic.com/v1/messages`. Trois en-têtes sont importants : votre clé, la version de l'API et le type de contenu.
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-5",
"max_tokens": 4096,
"messages": [
{"role": "user", "content": "Explain the difference between a 429 and a 529 from an API perspective."}
]
}'
Notez la valeur de `max_tokens`. 4096 est une augmentation délibérée par rapport aux 1024 que l'on voit dans la plupart des extraits de code de démarrage, car les jetons de réflexion proviennent désormais du même budget.
L'équivalent Python via le SDK officiel :
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
message = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
messages=[
{"role": "user", "content": "Explain the difference between a 429 and a 529 from an API perspective."}
],
)
for block in message.content:
if block.type == "text":
print(block.text)
Cette boucle sur `message.content` n'est pas décorative. Le `content` de la réponse est un tableau de blocs typés, et avec la réflexion activée, vous verrez désormais un bloc `thinking` avant le bloc `text`. Le code qui supposait que `content[0].text` était la réponse ne fonctionne plus sur Opus 5. C'est la défaillance de mise à niveau la plus courante, et elle est facile à manquer car la requête renvoie toujours un 200.
Quelques spécifications à garder à l'esprit pendant que vous construisez : Opus 5 a une fenêtre contextuelle de 1M de jetons, à la fois par défaut et maximale (pas d'en-tête bêta, pas de prime de prix pour le contexte long), une sortie maximale de 128k sur l'API Messages, et une date limite de connaissances de mai 2026. La vue d'ensemble des modèles contient le tableau complet, et notre explication d'Opus 5 couvre le reste de la fiche technique.
Étape 3 : Travailler avec la pensée adaptative
La pensée adaptative signifie que le modèle décide de la quantité de raisonnement interne qu'une requête mérite. Vous ne définissez pas de budget de jetons. Vous la dirigez avec l'effort, ce qui est couvert à l'étape suivante.
Ce que vous devez gérer dans le code :
- Analyser les blocs par type. Filtrez sur `block.type == "text"` pour la réponse visible et sur `block.type == "thinking"` si vous souhaitez enregistrer le raisonnement.
- Renvoyez les blocs de pensée inchangés. Dans les boucles multi-tours et d'utilisation d'outils, ajoutez le tableau de contenu complet de l'assistant à votre historique de messages plutôt que de le reconstruire à partir du texte. Supprimer des blocs en cours de conversation dégrade la boucle.
- Budgétisez `max_tokens` pour les deux. La réflexion et la réponse partagent la limite. La troncature apparaît sous la forme de `stop_reason: "max_tokens"`, assurez-vous donc de tester ce champ dans vos tests.
Pour désactiver complètement la réflexion :
{
"model": "claude-opus-5",
"max_tokens": 4096,
"thinking": {"type": "disabled"},
"output_config": {"effort": "high"},
"messages": [{"role": "user", "content": "Return only the HTTP status code."}]
}
L'effort est plafonné à `high` dans cette requête intentionnellement. Augmentez-le à `xhigh` et vous obtiendrez l'erreur 400 décrite ci-dessus.
Étape 4 : Contrôler les coûts avec output_config.effort
Le champ `effort` se trouve sous `output_config` et peut prendre les valeurs `low`, `medium`, `high`, `xhigh` ou `max`. Il est par défaut à `high`. C'est le paramètre que la couverture médiatique a décrit comme un interrupteur entre le coût et la capacité ; sur l'API, c'est une seule chaîne dans le corps de votre requête.
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-5",
"max_tokens": 65536,
"output_config": {"effort": "xhigh"},
"messages": [
{"role": "user", "content": "Refactor this handler to stream responses and keep backpressure."}
]
}'
Trois choses à savoir avant de l'ajuster.
Les niveaux sont recalibrés. Anthropic déconseille explicitement de reporter vos paramètres d'effort d'Opus 4.8. `low` et `medium` sont significativement plus puissants sur Opus 5 que sur les modèles Opus précédents, ce qui signifie que les charges de travail que vous exécutiez auparavant à `high` peuvent désormais être gérées à moindre coût. Effectuez une nouvelle évaluation par rapport à vos propres évaluations plutôt que de vous fier à une correspondance.
`xhigh` reste le point de départ recommandé pour le codage et le travail d'agent. C'est aussi là que `max_tokens` est le plus important. Donnez-lui de l'espace ; 64k est une limite de départ raisonnable pour les longs tours d'agent, c'est pourquoi l'extrait ci-dessus utilise 65536.
Un effort moindre réduit la réflexion, pas la longueur visible. Les réponses par défaut et les livrables écrits d'Opus 5 sont plus longs que ceux d'Opus 4.8. Si vous souhaitez une sortie plus courte, demandez-le dans le prompt. Passer à `low` ne le fera pas pour vous. L'analyse approfondie du paramètre d'effort décrit une méthodologie complète d'évaluation.
Étape 5 : Diffuser la réponse en continu (Streaming)
Ajoutez `\"stream\": true` et le point de terminaison renverra des événements envoyés par le serveur au lieu d'un seul corps JSON.
with client.messages.stream(
model="claude-opus-5",
max_tokens=4096,
messages=[{"role": "user", "content": "Draft a retry policy for a flaky upstream."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
final = stream.get_final_message()
print("\n\nusage:", final.usage)
La séquence SSE brute est `message_start`, puis `content_block_start` / `content_block_delta` / `content_block_stop` par bloc, puis `message_delta` transportant `stop_reason` et le nombre final de jetons de sortie, puis `message_stop`.
Avec la réflexion activée, vous recevez deux blocs de contenu en streaming dans l'ordre : un bloc de réflexion dont les deltas arrivent comme `thinking_delta`, puis le bloc de texte avec `text_delta`. Une interface utilisateur qui affiche chaque delta dans le même tampon imprimera le raisonnement du modèle à vos utilisateurs. Dirigez-les séparément dès le début.
Le streaming est également l'endroit où un client GUI prend toute sa place, car la lecture de SSE bruts dans un terminal est pénible. Apidog affiche le flux d'événements à mesure qu'il arrive, vous pouvez donc observer les limites des blocs et confirmer vos hypothèses de parsing avant d'écrire une seule ligne de code de gestionnaire.
Étape 6 : Ajouter l'utilisation d'outils
Les définitions d'outils sont placées dans un tableau `tools`. Le modèle répond avec `stop_reason: "tool_use"` et un bloc de contenu `tool_use` ; vous exécutez l'outil et renvoyez le résultat sous forme de bloc `tool_result` dans un nouveau message utilisateur.
tools = [
{
"name": "get_order_status",
"description": "Look up the current status of a customer order by ID.",
"input_schema": {
"type": "object",
"properties": {
"order_id": {"type": "string", "description": "The order ID, e.g. A-10293"}
},
"required": ["order_id"],
},
}
]
message = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
tools=tools,
messages=[{"role": "user", "content": "What's the status of order A-10293?"}],
)
if message.stop_reason == "tool_use":
call = next(b for b in message.content if b.type == "tool_use")
result = get_order_status(**call.input)
follow_up = client.messages.create(
model="claude-opus-5",
max_tokens=4096,
tools=tools,
messages=[
{"role": "user", "content": "What's the status of order A-10293?"},
{"role": "assistant", "content": message.content},
{"role": "user", "content": [
{"type": "tool_result", "tool_use_id": call.id, "content": result}
]},
],
)
Transmettre `message.content` directement comme tour de l'assistant est ce qui préserve le bloc de réflexion. Ne reconstruisez pas ce tour manuellement.
Deux détails d'Opus 5 importants pour les agents. La surcharge du prompt système pour l'utilisation d'outils est inférieure à celle d'Opus 4.8 : 286 jetons avec `tool_choice` défini sur `auto` ou `none`, contre 290 sur 4.8 et 675 sur Opus 4.7. Petit par requête, mais significatif sur un million de tours d'agent. Et il existe un en-tête bêta, `mid-conversation-tool-changes-2026-07-01`, qui vous permet d'ajouter ou de supprimer des outils entre les tours sans invalider le cache du prompt.
Opus 5 délègue également aux sous-agents plus facilement que ne le faisait 4.8. Pour les charges de travail sensibles aux coûts, définissez cela explicitement dans votre prompt système plutôt que de le découvrir sur la facture.
Étape 7 : Lire l'objet d'utilisation pour les succès de cache
Chaque réponse contient un objet `usage`. C'est le seul moyen honnête de confirmer que votre cache de prompt fonctionne.
"usage": {
"input_tokens": 84,
"cache_creation_input_tokens": 6421,
"cache_read_input_tokens": 0,
"output_tokens": 913
}
Pour mettre un bloc en cache, marquez-le avec `cache_control` :
{
"model": "claude-opus-5",
"max_tokens": 4096,
"system": [
{
"type": "text",
"text": "<your long, stable instructions and reference material>",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [{"role": "user", "content": "Question one."}]
}
Premier appel : `cache_creation_input_tokens` est non nul et `cache_read_input_tokens` est 0. Deuxième appel avec le même préfixe : ces valeurs s'inversent. Si elles ne s'inversent jamais, votre préfixe n'est pas identique au niveau des octets ou il est inférieur au minimum.
Ce minimum est la bonne nouvelle sur Opus 5. Le cache de prompt se déclenche désormais à 512 jetons, contre 1 024 sur Opus 4.8. Les prompts qui étaient trop courts pour être mis en cache auparavant le sont désormais sans aucune modification de code, et les lectures de cache sont facturées 0,50 $ par million de jetons contre un tarif d'entrée de base de 5 $. Assurez-vous que `cache_read_input_tokens` est testé dans votre suite de tests afin qu'une modification de prompt qui invalide silencieusement le cache apparaisse comme un test échoué plutôt que comme une facture. Pour plus de leviers, consultez notre guide sur la réduction de votre facture API Claude.
Tester et déboguer le flux complet dans Apidog
Tout ce qui précède est une requête HTTP avec des en-têtes d'authentification, un corps JSON, un flux SSE et une réponse que vous devez valider. Apidog est une plateforme de développement API tout-en-un, et c'est précisément le type de point de terminaison qu'elle gère : elle envoie la requête, stocke la clé, affiche le flux et teste la réponse. Elle n'effectue pas d'inférence ni de routage de modèles ; l'appel va toujours à Anthropic.
Une configuration qui se rentabilise dès le premier jour :
- Créez la requête. `POST https://api.anthropic.com/v1/messages` avec les trois en-têtes, et la clé extraite d'une variable d'environnement au lieu d'être collée en ligne.
- Enregistrez-la dans une collection. Votre équipe réutilise une forme de requête connue et validée plutôt que chaque personne la reconstruisant à partir d'un extrait de blog.
- Dupliquez-la par niveau d'effort. Dupliquez la requête avec `output_config.effort` défini sur `low`, `medium`, `high` et `xhigh`, envoyez le même prompt à chacune, et comparez la qualité de sortie, la latence et le nombre de jetons côte à côte. C'est l'évaluation d'effort qu'Anthropic vous demande d'effectuer, sans écrire de harnais.
- Surveillez le flux SSE. Activez `\"stream\": true` et lisez les événements à mesure qu'ils arrivent pour confirmer que vous gérez les blocs de réflexion et les blocs de texte séparément.
- Inspectez les charges utiles des appels d'outils. Lorsque `stop_reason` renvoie `tool_use`, l'objet `input` exact produit par le modèle est là, ce qui vous permet de découvrir que votre `input_schema` était trop permissif.
- Validez la réponse. Ajoutez des vérifications que `stop_reason` n'est pas `max_tokens` (votre indicateur de troncature) et que `cache_read_input_tokens` est supérieur à zéro lors des appels répétés (votre indicateur de mise en cache).
Téléchargez Apidog si vous voulez suivre. Le même modèle de collection fonctionne avec n'importe quel modèle Claude, vous pouvez donc le diriger vers Sonnet 5 ou vos requêtes Opus 4.8 existantes et comparer les comportements.
Erreurs et pièges que vous rencontrerez réellement
- 400 sur `thinking: disabled` plus effort `xhigh` ou `max`. Couvert ci-dessus. Réduisez l'effort à `high` ou réactivez la réflexion.
- 400 sur les paramètres d'échantillonnage. `temperature`, `top_p` et `top_k` à des valeurs non par défaut renvoient toujours une erreur 400, inchangé par rapport à Opus 4.8. Orientez plutôt via le prompt système.
- Réponses tronquées. `stop_reason: "max_tokens"` avec la réflexion activée signifie que la limite a coupé votre réponse. Augmentez `max_tokens`.
- Le niveau de priorité n'est pas pris en charge sur Opus 5. Opus 4.8 le conserve. Si la planification de la capacité de votre entreprise en dépend, c'est un véritable obstacle à résoudre avant de basculer le trafic.
- Les messages système en milieu de conversation fonctionnent désormais. Une entrée `role: "system"` à l'intérieur des `messages` est acceptée sur Opus 5, alors qu'Opus 4.8 renvoyait une erreur 400. Utile, et bon à savoir pour ne pas continuer à le contourner.
- Sur-vérification. Opus 5 vérifie son propre travail sans y être invité. Si vous avez reporté une instruction « double-vérifiez votre réponse avant de répondre » de la version 4.8, supprimez-la. Cela ne vous apporte rien et coûte des jetons de réflexion.
Le plafond honnête
Opus 5 n'est pas le sommet de la pile Claude, et il est bon de le dire clairement. Fable 5 détient toujours la désignation d'Anthropic de « le plus capable largement diffusé », à 10 $ par million de jetons d'entrée et 50 $ par million de jetons de sortie. Opus 5 est également devancé par Mythos 5 en matière d'exploitation de la cybersécurité et de recherche en biologie autonome, ce qu'Anthropic déclare elle-même.
Les affirmations des benchmarks de lancement (environ le double d'Opus 4.8 sur Frontier-Bench v0.1, environ 3 fois le meilleur modèle suivant sur ARC-AGI 3, à 0,5% près de Fable 5 sur CursorBench 3.2) sont toutes des chiffres propres à Anthropic et n'ont pas été reproduites indépendamment au 25 juillet 2026. Lisez-les comme des résultats fournis par le fournisseur, puis effectuez vos propres évaluations. La comparaison Opus 5 versus Fable 5 explique où l'écart de prix en vaut la peine et où il ne l'est pas, et le billet de lancement d'Anthropic est la source principale des affirmations elles-mêmes.
FAQ
Quel est l'ID du modèle pour Claude Opus 5 ? `claude-opus-5`, exactement, sans suffixe de date. Sur Amazon Bedrock, c'est `anthropic.claude-opus-5` ; Google Cloud et la plateforme Claude sur AWS utilisent l'ID propriétaire.
Pourquoi ma requête Opus 4.8 fonctionnelle a-t-elle commencé à tronquer sur Opus 5 ? La réflexion est maintenant activée par défaut. `max_tokens` plafonne les jetons de réflexion et les jetons de réponse ensemble, donc un budget qui suffisait pour votre réponse sur 4.8 peut ne plus suffire pour le raisonnement plus la réponse sur Opus 5. Augmentez `max_tokens` et vérifiez `stop_reason: "max_tokens"`.
Pourquoi est-ce que j'obtiens une erreur 400 lorsque je désactive la réflexion ? Vous avez presque certainement associé `thinking: {"type": "disabled"}` à `output_config.effort` défini sur `xhigh` ou `max`. Cette combinaison est rejetée par requête. Plafonnez l'effort à `high`, ou maintenez la réflexion activée et réduisez l'effort à la place.
Ai-je besoin d'un en-tête bêta pour la fenêtre contextuelle de 1M ? Non. Sur Opus 5, 1M de jetons est à la fois la valeur par défaut et le maximum, sans en-tête bêta et sans surcoût pour un contexte long. Vous avez besoin de l'en-tête bêta `output-300k-2026-03-24` pour atteindre 300k de sortie sur l'API Batch ; l'API Messages plafonne la sortie à 128k.
Puis-je réutiliser mes paramètres d'effort d'Opus 4.8 ? Anthropic dit non. Les niveaux ont été recalibrés, et `low` et `medium` sont significativement plus puissants sur Opus 5. Effectuez une nouvelle évaluation par rapport à votre propre ensemble d'évaluation.
Apidog exécute-t-il le modèle ? Non. Apidog envoie, inspecte et teste la requête HTTP ; l'inférence se produit du côté d'Anthropic. Il gère les clés, le streaming, les charges utiles des appels d'outils et les assertions de réponse autour de l'appel.