DEV Community

Cover image for Comment utiliser l'API Claude Opus 5
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment utiliser l'API Claude Opus 5

Claude Opus 5 a été lancé le 24 juillet 2026, et Anthropic oriente désormais les développeurs vers ce modèle en premier : si vous ne savez pas quel modèle utiliser, commencez par Claude Opus 5. Son ID API exact est claude-opus-5, sans suffixe de date.

Essayez Apidog dès aujourd’hui

Ce guide couvre le flux complet : création de clé API, première requête, streaming, appels d’outils, pensée adaptative, paramètre effort et lecture de l’objet usage pour vérifier le cache de prompt. Chaque exemple utilise HTTP et JSON : vous pouvez donc construire et déboguer les requêtes dans Apidog avant de les intégrer à votre application.

Si vous migrez depuis Opus 4.8, consultez aussi le guide de migration d’Opus 4.8 vers Opus 5.

Avant votre premier appel : deux changements majeurs

1. La réflexion est activée par défaut

Avec Opus 4.8, une requête sans champ thinking s’exécutait sans réflexion. Avec Opus 5, la même requête utilise une pensée adaptative.

Le paramètre max_tokens reste une limite stricte qui couvre à la fois :

  • les jetons de réflexion ;
  • les jetons de réponse visibles.

Une requête héritée d’Opus 4.8 peut donc être tronquée avec Opus 5. Si votre ancien max_tokens était calculé uniquement pour la longueur attendue de la réponse, augmentez-le.

2. Désactiver la réflexion limite le niveau d’effort

La combinaison suivante renvoie une erreur HTTP 400 :

{
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "xhigh"}
}
Enter fullscreen mode Exit fullscreen mode

Lorsque thinking est désactivé, effort ne peut pas dépasser high.

Deux options sont possibles :

  1. laisser la réflexion activée et réduire effort pour maîtriser les coûts ;
  2. désactiver la réflexion et limiter effort à high.

Anthropic recommande la première option. Sans réflexion, Opus 5 peut occasionnellement écrire des appels d’outils en texte brut ou laisser apparaître des balises <thinking> dans la sortie visible. Garder la réflexion activée réduit ces problèmes dans les boucles d’agents.

Ces changements sont décrits dans le guide de migration de modèle d’Anthropic.

Étape 1 : obtenir une clé API

Connectez-vous à la plateforme développeur Claude, ouvrez les paramètres de votre organisation, puis créez une clé API. Copiez-la immédiatement : elle ne pourra pas être relue ensuite.

Stockez-la dans une variable d’environnement :

export ANTHROPIC_API_KEY="sk-ant-..."
Enter fullscreen mode Exit fullscreen mode

N’insérez pas la clé directement dans le code ou dans une collection exportée.

Dans Apidog, créez par exemple des environnements Local, Staging et Production, chacun avec une variable ANTHROPIC_API_KEY. Référencez ensuite la clé dans l’en-tête avec :

{{ANTHROPIC_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

Vos requêtes restent partageables, sans exposer le secret.

Configuration d’une variable d’environnement dans Apidog

Ajoutez également des crédits de facturation avant d’envoyer des requêtes. Opus 5 est facturé 5 $ par million de jetons d’entrée et 25 $ par million de jetons de sortie, comme Opus 4.8. Consultez la répartition complète des tarifs pour le caching, le batch et le mode rapide.

Étape 2 : envoyer votre première requête

Utilisez l’endpoint suivant :

POST https://api.anthropic.com/v1/messages
Enter fullscreen mode Exit fullscreen mode

Ajoutez ces trois en-têtes :

  • x-api-key
  • anthropic-version
  • content-type

Exemple avec curl :

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Ici, max_tokens: 4096 est volontairement supérieur aux 1024 souvent utilisés dans les exemples de démarrage : la réflexion et la réponse visible partagent désormais le même budget.

Équivalent Python avec 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)
Enter fullscreen mode Exit fullscreen mode

Ne supposez pas que message.content[0] contient du texte. Avec la réflexion activée, content peut contenir :

  1. un bloc thinking ;
  2. un bloc text.

Parcourez toujours les blocs par type. Une intégration qui lit directement content[0].text peut obtenir un 200 OK tout en ne récupérant pas la réponse attendue.

Points techniques à retenir :

  • fenêtre contextuelle : 1 million de jetons ;
  • sortie maximale sur l’API Messages : 128k jetons ;
  • date limite de connaissances : mai 2026.

Consultez la vue d’ensemble des modèles et cette présentation d’Opus 5.

Étape 3 : gérer la pensée adaptative

La pensée adaptative laisse le modèle déterminer la quantité de raisonnement interne nécessaire. Vous ne définissez pas de budget de réflexion dédié : vous orientez ce comportement avec output_config.effort.

Dans votre code, appliquez ces règles :

  • Parsez les blocs par type. Affichez seulement les blocs text à vos utilisateurs.
  • Conservez les blocs de pensée. Dans une conversation multi-tours ou une boucle d’outils, renvoyez le tableau message.content complet.
  • Testez la troncature. Vérifiez stop_reason == "max_tokens" dans vos tests.
  • Prévoyez un budget suffisant. max_tokens couvre la réflexion et la réponse.

Pour désactiver explicitement 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."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Dans cet exemple, effort est plafonné à high. Le remplacer par xhigh ou max provoque une erreur 400.

Étape 4 : contrôler les coûts avec output_config.effort

Définissez l’effort sous output_config :

{
  "output_config": {
    "effort": "xhigh"
  }
}
Enter fullscreen mode Exit fullscreen mode

Les valeurs disponibles sont :

  • low
  • medium
  • high
  • xhigh
  • max

La valeur par défaut est high.

Exemple pour une tâche longue de code ou d’agent :

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Avant de modifier ce paramètre, retenez les points suivants.

Les niveaux ont été recalibrés

Ne reportez pas directement les réglages d’effort d’Opus 4.8. Avec Opus 5, low et medium sont significativement plus capables que sur les modèles Opus précédents.

Évaluez chaque niveau sur vos propres prompts, vos tests et vos contraintes de qualité.

xhigh est recommandé pour le code et les agents

Pour les tâches longues, xhigh est un point de départ recommandé. Augmentez aussi max_tokens : 65536 est une limite initiale raisonnable pour un long tour d’agent.

Réduire l’effort ne raccourcit pas nécessairement la sortie

Un effort inférieur réduit surtout la réflexion, pas la taille de la réponse visible. Si vous voulez une réponse concise, indiquez-le explicitement dans votre prompt.

Pour une méthode d’évaluation plus complète, consultez l’analyse du paramètre effort.

Étape 5 : streamer la réponse

Ajoutez "stream": true pour recevoir des événements SSE au lieu d’un unique JSON final.

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)
Enter fullscreen mode Exit fullscreen mode

La séquence SSE brute est la suivante :

message_start
content_block_start
content_block_delta
content_block_stop
message_delta
message_stop
Enter fullscreen mode Exit fullscreen mode

Avec la réflexion activée, les blocs arrivent généralement dans cet ordre :

  1. bloc thinking avec des événements thinking_delta ;
  2. bloc text avec des événements text_delta.

Ne concaténez pas tous les deltas dans le même buffer UI. Sinon, vous risquez d’afficher le raisonnement interne au même endroit que la réponse utilisateur.

Le streaming est également plus simple à inspecter dans Apidog, qui affiche les événements SSE à mesure qu’ils arrivent. Vous pouvez ainsi valider votre parsing avant d’implémenter votre gestionnaire de streaming.

Étape 6 : ajouter l’utilisation d’outils

Déclarez les outils dans le tableau tools. Lorsque le modèle demande un outil :

  1. il répond avec stop_reason: "tool_use" ;
  2. vous exécutez l’outil côté application ;
  3. vous renvoyez un bloc tool_result dans un nouveau message utilisateur.

Exemple Python :

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(block for block in message.content if block.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,
                    }
                ],
            },
        ],
    )
Enter fullscreen mode Exit fullscreen mode

Le point important est de transmettre message.content directement dans le tour assistant. Ne recréez pas ce message à la main : vous perdriez notamment le bloc de réflexion.

Autres éléments utiles pour les agents :

  • la surcharge système liée aux outils est de 286 jetons avec tool_choice: "auto" ou "none", contre 290 sur Opus 4.8 et 675 sur Opus 4.7 ;
  • l’en-tête bêta mid-conversation-tool-changes-2026-07-01 permet d’ajouter ou retirer des outils entre les tours sans invalider le cache de prompt ;
  • Opus 5 délègue plus facilement à des sous-agents que 4.8 : définissez explicitement les limites de délégation dans votre prompt système si le coût est sensible.

Étape 7 : vérifier le cache avec l’objet usage

Chaque réponse contient un objet usage :

{
  "input_tokens": 84,
  "cache_creation_input_tokens": 6421,
  "cache_read_input_tokens": 0,
  "output_tokens": 913
}
Enter fullscreen mode Exit fullscreen mode

Pour rendre un bloc éligible au cache, ajoutez 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."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Interprétez ensuite usage ainsi :

  • Premier appel : cache_creation_input_tokens > 0 et cache_read_input_tokens == 0.
  • Appel suivant avec le même préfixe : cache_read_input_tokens > 0.

Si le cache n’est jamais lu, vérifiez que votre préfixe est strictement identique au niveau des octets et qu’il atteint le seuil minimum.

Avec Opus 5, le cache de prompt démarre dès 512 jetons, contre 1 024 avec Opus 4.8. Les lectures de cache sont facturées 0,50 $ par million de jetons, contre 5 $ par million de jetons d’entrée au tarif de base.

Ajoutez une assertion automatisée, par exemple :

assert response.usage.cache_read_input_tokens > 0
Enter fullscreen mode Exit fullscreen mode

sur les appels répétés qui doivent réutiliser le cache. Une modification de prompt qui casse le cache devient alors un échec de test plutôt qu’une surprise sur la facture.

Pour aller plus loin, consultez ce guide sur la réduction de votre facture API Claude.

Tester le flux complet dans Apidog

Le flux décrit ici repose uniquement sur HTTP :

  • en-têtes d’authentification ;
  • corps JSON ;
  • flux SSE ;
  • réponse à valider.

Apidog permet d’envoyer les requêtes, de stocker les secrets dans des environnements, d’inspecter les flux et de tester les réponses. L’inférence et le routage des modèles restent effectués par Anthropic.

Test d’une requête Claude dans Apidog

Configuration recommandée :

  1. Créez la requête. Utilisez POST https://api.anthropic.com/v1/messages, les trois en-têtes requis et une variable d’environnement pour la clé.
  2. Enregistrez-la dans une collection. L’équipe partage une requête validée plutôt que de recréer la configuration à partir d’exemples.
  3. Dupliquez-la par niveau d’effort. Créez une version pour low, medium, high et xhigh, puis comparez qualité, latence et consommation de jetons avec le même prompt.
  4. Inspectez le flux SSE. Activez "stream": true et vérifiez que les blocs thinking et text sont traités séparément.
  5. Examinez les appels d’outils. Quand stop_reason vaut tool_use, inspectez précisément l’objet input généré pour renforcer un schéma input_schema trop permissif.
  6. Ajoutez des assertions. Vérifiez que stop_reason n’est pas max_tokens et que cache_read_input_tokens devient supérieur à zéro sur les appels répétés.

Téléchargez Apidog pour reproduire ce flux. La même collection peut être dirigée vers Sonnet 5 ou vers vos requêtes Opus 4.8 existantes afin de comparer les comportements.

Erreurs et pièges fréquents

  • Erreur 400 avec thinking: disabled et effort: xhigh ou max. Réduisez effort à high, ou réactivez la réflexion.
  • Erreur 400 avec les paramètres d’échantillonnage. Les valeurs non par défaut de temperature, top_p et top_k sont toujours rejetées. Utilisez plutôt le prompt système pour orienter la sortie.
  • Réponses tronquées. Si stop_reason vaut "max_tokens", augmentez max_tokens.
  • Niveau de priorité non pris en charge. Opus 5 ne le prend pas en charge, alors qu’Opus 4.8 le conserve. Vérifiez ce point avant de migrer du trafic dépendant de cette capacité.
  • Messages système au milieu de la conversation. Opus 5 accepte désormais une entrée role: "system" dans messages, là où Opus 4.8 renvoyait une erreur 400.
  • Sur-vérification dans le prompt. Opus 5 vérifie déjà son travail sans instruction explicite. Supprimez les formulations héritées comme « double-vérifiez votre réponse avant de répondre » si elles n’apportent pas de valeur mesurable.

Le plafond honnête

Opus 5 n’est pas le sommet de la pile Claude. Fable 5 conserve la désignation Anthropic de « le plus capable largement diffusé », à 10 $ par million de jetons d’entrée et 50 $ par million de jetons de sortie. Anthropic indique également que Mythos 5 dépasse Opus 5 pour l’exploitation de la cybersécurité et la recherche autonome en biologie.

Les benchmarks de lancement — environ deux fois Opus 4.8 sur Frontier-Bench v0.1, environ trois fois le meilleur modèle suivant sur ARC-AGI 3, et à 0,5 % près de Fable 5 sur CursorBench 3.2 — sont des chiffres publiés par Anthropic et n’étaient pas reproduits indépendamment au 25 juillet 2026.

Traitez-les comme des résultats fournis par le fournisseur, puis exécutez vos propres évaluations. Consultez la comparaison Opus 5 versus Fable 5 ainsi que le billet de lancement d’Anthropic.

FAQ

Quel est l’ID du modèle Claude Opus 5 ?

claude-opus-5, exactement, sans suffixe de date.

Sur Amazon Bedrock, utilisez anthropic.claude-opus-5. Google Cloud et la plateforme Claude sur AWS utilisent l’ID propriétaire.

Pourquoi ma requête Opus 4.8 est-elle tronquée sur Opus 5 ?

La réflexion est activée par défaut. max_tokens couvre maintenant les jetons de réflexion et de réponse. Augmentez cette limite et vérifiez stop_reason: "max_tokens".

Pourquoi obtenir une erreur 400 lorsque je désactive la réflexion ?

Vous avez probablement combiné :

{
  "thinking": {"type": "disabled"},
  "output_config": {"effort": "xhigh"}
}
Enter fullscreen mode Exit fullscreen mode

Avec la réflexion désactivée, limitez effort à high ou moins.

Faut-il un en-tête bêta pour la fenêtre de contexte de 1M ?

Non. Pour Opus 5, 1 million de jetons est à la fois la valeur par défaut et le maximum, sans en-tête bêta ni surcoût de contexte long.

L’en-tête bêta output-300k-2026-03-24 est nécessaire pour atteindre 300k de sortie avec l’API Batch. L’API Messages est plafonnée à 128k de sortie.

Puis-je réutiliser les réglages d’effort d’Opus 4.8 ?

Non. Anthropic indique que les niveaux ont été recalibrés. Réévaluez low, medium, high et xhigh avec vos propres jeux de tests.

Apidog exécute-t-il le modèle ?

Non. Apidog envoie, inspecte et teste les requêtes HTTP. L’inférence est effectuée par Anthropic. Apidog vous aide à gérer les clés, le streaming, les appels d’outils et les assertions de réponse.

Top comments (0)