Comment utiliser l'API Claude Sonnet 5 (Étape par étape avec Apidog)

Claude Sonnet 5 a été lancé le 30 juin 2026, et c'est le modèle Sonnet le plus autonome qu'Anthropic ait publié. Il atteint des performances proches d'Opus 4.8 sur les tâches d'utilisation d'outils et de codage à un prix bien inférieur, ce qui en fait un excellent choix par défaut pour tout ce qui utilise des outils en boucle. Ce guide vous montre comment appeler l'API Claude Sonnet 5 de bout en bout : obtenir une clé, envoyer votre première requête en curl et Python, lire la réponse, gérer le nouveau comportement par défaut de la pensée adaptative, éviter les trois modifications de requête qui renvoient des erreurs 400, diffuser les sorties longues en continu et compter les jetons avec le nouveau tokenizeur. Vous configurerez également le tout dans Apidog afin que vos requêtes résident dans une collection réutilisable avec des environnements enregistrés et des tests automatisés, au lieu d'être dispersées dans l'historique de votre shell. Si vous avez déjà appelé l'API Messages, la plupart de ces informations vous sembleront familières. L'ID du modèle est `claude-sonnet-5`, et la structure de la requête correspond à ce que vous utilisez déjà.

Ce dont vous avez besoin avant de commencer

Vous avez besoin de trois choses pour appeler l'API.

• Un compte Anthropic et une clé API depuis la console de la plateforme Claude.
• L'ID du modèle : `claude-sonnet-5`. C'est la chaîne de caractères exacte, sans suffixe de date.
• Un moyen d'envoyer des requêtes HTTP. curl fonctionne pour un test rapide. Apidog fonctionne mieux une fois que vous itérez.

Sonnet 5 est disponible pour tous les clients de l'API, ainsi que pour Amazon Bedrock (via la plateforme Claude sur AWS), Google Cloud via Vertex AI, et Microsoft Foundry en préversion. Ce guide utilise l'API Anthropic directe. Le corps de la requête est le même sur toutes les plateformes ; seuls l'authentification et l'hôte de l'endpoint changent.

Obtenez votre clé API

Connectez-vous à la console de la plateforme Claude, ouvrez la section des clés API et créez une nouvelle clé. Copiez-la une seule fois et stockez-la en lieu sûr, car la console ne l'affichera plus. Ne jamais coder en dur la clé dans votre code source ou la commettre dans git. Définissez-la plutôt comme variable d'environnement :

export ANTHROPIC_API_KEY="sk-ant-..."

Si vous êtes sous un accord ZDR, Sonnet 5 prend en charge la rétention nulle des données, donc rien ne change concernant l'interface de l'API pour vous ici.

Votre première requête

L'API Sonnet 5 utilise l'endpoint Messages d'Anthropic. Voici une requête minimale avec curl.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Write a haiku about API testing."}
    ]
  }'

La même requête avec le SDK Python :

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Write a haiku about API testing."}
    ],
)

print(message.content[0].text)

Deux champs font le gros du travail. `model` sélectionne Sonnet 5. `max_tokens` plafonne la sortie totale. Continuez à lire, car `max_tokens` se comporte différemment sur Sonnet 5 que sur Sonnet 4.6, et c'est la chose la plus facile à mal comprendre.

Lecture de la réponse

Un appel réussi renvoie HTTP 200 avec un corps JSON comme celui-ci (tronqué) :

{
  "id": "msg_01ABC...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    {"type": "text", "text": "Assertions green,\nendpoints answer on the first try,\nship the merge tonight."}
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 27
  }
}

Quelques champs sont importants pour le travail réel.

• `content` est un tableau. Le texte se trouve dans des blocs où `type` est `"text"`. Avec l'utilisation d'outils ou la pensée activée, vous verrez d'autres types de blocs dans le même tableau, alors itérez ; ne supposez pas que `content[0]` est toujours votre réponse.
• `stop_reason` vous indique pourquoi la génération s'est terminée. `end_turn` est normal. `max_tokens` signifie que vous avez atteint la limite et que la sortie a été tronquée. `refusal` est nouveau et mérite d'être compris (ci-dessous).
• `usage` signale les `input_tokens` et `output_tokens`. C'est ce sur quoi vous êtes facturé, et les chiffres sont plus élevés sur Sonnet 5 pour le même texte à cause du nouveau tokenizeur.

La raison d'arrêt « refusal »

Sonnet 5 est le premier modèle de la catégorie Sonnet avec des protections de cybersécurité en temps réel. Si une requête touche un sujet cybernétique prohibé ou à haut risque, le modèle peut refuser. Un refus est renvoyé comme un HTTP 200 normal avec `stop_reason: "refusal"`, et non comme une erreur. Gérez-le dans votre code d'analyse de réponse de la même manière que vous géreriez toute raison d'arrêt autre que `end_turn`, plutôt que de le traiter comme un appel HTTP échoué.

La pensée adaptative est activée par défaut

C'est le plus grand changement de comportement par rapport à Sonnet 4.6, et il induit les gens en erreur. Sur Sonnet 4.6, pas de champ `thinking` signifiait pas de pensée. Sur Sonnet 5, la pensée adaptative est activée par défaut. Une requête sans champ `thinking` s'exécute maintenant avec la pensée adaptative, et les jetons de pensée comptent pour votre sortie totale.

Étant donné que `max_tokens` est un plafond strict sur la sortie totale (jetons de pensée plus texte de réponse), une valeur `max_tokens` qui était confortable sur 4.6 peut maintenant tronquer votre réponse visible avant qu'elle ne se termine. Si vous avez migré une charge de travail qui n'a jamais utilisé la pensée et défini un `max_tokens` strict, augmentez-le ou attendez-vous à une troncature.

Pour désactiver complètement la pensée :

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    thinking={"type": "disabled"},
    messages=[
        {"role": "user", "content": "Return only the JSON, no reasoning."}
    ],
)

Pour garder la pensée adaptative activée et contrôler à quel point le modèle travaille dur, utilisez le paramètre d'effort au lieu d'essayer de définir un budget de jetons manuel. L'effort prend en charge `low`, `medium`, `high` et `xhigh`. Un effort plus élevé signifie une pensée plus profonde et une plus grande consommation de jetons. Anthropic documente ce comportement sur la page adaptive thinking. Notez que la valeur du champ est `{"type": "adaptive"}`, pas un nombre `budget_tokens`.

Trois modifications de requête qui renvoient des erreurs 400

Si vous portez du code de Sonnet 4.6 ou d'un ancien modèle Claude, trois choses qui fonctionnaient auparavant renvoient maintenant une erreur 400. Corrigez-les avant de migrer.

1. La pensée étendue manuelle est supprimée. `thinking: {type: "enabled", budget_tokens: N}` renvoie 400. Elle était déjà dépréciée sur 4.6. Utilisez plutôt la pensée adaptative plus le paramètre d'effort.
2. Les paramètres d'échantillonnage sont rejetés. Définir `temperature`, `top_p` ou `top_k` à une valeur non-par défaut renvoie 400. Supprimez-les. Les omettre, ou les laisser à leur valeur par défaut, est acceptable. Orienter le comportement avec des instructions de prompt système à la place. Cette contrainte était déjà présente sur Opus 4.7 et versions ultérieures ; elle est nouvelle pour la classe Sonnet.
3. Le pré-remplissage des messages de l'assistant n'est pas pris en charge. Le pré-remplissage du début du tour de l'assistant renvoie 400. Utilisez plutôt des sorties structurées ou `output_config.format` ou des instructions de prompt système pour façonner la sortie.

Tout le reste qui fonctionne sur Sonnet 4.6 fonctionne sur Sonnet 5 sans aucune autre modification de code. Les structures de requête, de réponse et de streaming sont identiques. Pour une présentation plus complète de la migration, consultez notre guide sur l'API Claude Sonnet 4.6, qui couvre la même surface de requête dont Sonnet 5 hérite.

Streaming pour les sorties volumineuses

Sonnet 5 prend en charge jusqu'à 128 000 jetons de sortie. Pour les réponses longues, ou toute requête où la pensée adaptative augmente considérablement la sortie totale, diffusez le résultat en continu afin d'obtenir les jetons au fur et à mesure qu'ils sont générés au lieu d'attendre la réponse complète. Le streaming évite également les délais d'attente client pour les grandes générations.

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8000,
    messages=[
        {"role": "user", "content": "Draft an OpenAPI 3.1 spec for a bookstore checkout API."}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

La structure de l'événement de streaming est la même que sur Sonnet 4.6, de sorte que les gestionnaires de flux existants fonctionnent sans modification.

Comptage des jetons avec le nouveau tokenizeur

Sonnet 5 utilise un nouveau tokenizeur. Le même texte d'entrée produit environ 30 % de jetons en plus que sur Sonnet 4.6, soit environ 1,3 fois plus. Ce n'est pas un changement d'API. Les structures de requête, de réponse et de streaming sont identiques, et vous n'avez pas besoin de modifier votre code pour cela. Mais cela affecte tout ce que vous mesurez ou budgétisez en jetons.

• Vos chiffres d'utilisation et les résultats du comptage de jetons sont plus élevés pour le même texte. Recomptez avec Sonnet 5 ; ne réutilisez pas vos comptes de 4.6.
• La fenêtre de contexte de 1 000 000 de jetons contient moins de texte en moyenne, car chaque jeton couvre désormais moins de texte.
• Une valeur `max_tokens` dimensionnée près de votre sortie attendue peut maintenant tronquer. Revoyez-le.
• Le coût par requête pour un texte équivalent peut être plus élevé même si le prix par jeton est inchangé.

Utilisez l'endpoint de comptage de jetons avant d'envoyer, afin de budgétiser sur les vrais chiffres de Sonnet 5 :

count = client.messages.count_tokens(
    model="claude-sonnet-5",
    messages=[
        {"role": "user", "content": "Estimate the tokens for this prompt on Sonnet 5."}
    ],
)
print(count.input_tokens)

Anthropic documente cela sur la page token counting.

Erreurs, limites de débit et notions de coût

La sémantique HTTP standard s'applique. Un 400 signifie une requête mal formée (les trois changements ci-dessus sont les suspects habituels sur Sonnet 5). Un 401 signifie une clé API incorrecte ou manquante. Un 429 signifie que vous avez atteint une limite de débit. Lisez l'en-tête `retry-after` et attendez avant de réessayer. N'oubliez pas qu'un refus est un 200, pas une erreur, donc ne le dirigez pas via votre logique de nouvelle tentative.

Concernant la tarification, le tarif de lancement est de 2 $ par million de jetons d'entrée et 10 $ par million de jetons de sortie, en vigueur jusqu'au 31 août 2026. Après cela, il passera au standard de 3 $ par million d'entrée et 15 $ par million de sortie, soit le même tarif par jeton que Sonnet 4.6. En raison du changement de tokenizeur, le coût d'une requête de texte équivalent peut toujours être plus élevé que sur 4.6 même si le tarif par jeton correspond, alors modélisez vos charges de travail réelles avec le comptage de jetons au lieu de supposer une parité plate. Pour une présentation plus approfondie des coûts, consultez notre ventilation des coûts de l'API Claude et le guide des limites de débit de l'API Claude. Le niveau de priorité n'est pas disponible sur Sonnet 5.

Testez et organisez vos appels Sonnet 5 dans Apidog

Une fois que vous avez dépassé la première commande curl, vous voulez que vos requêtes soient enregistrées, votre clé stockée une seule fois et vos réponses vérifiées automatiquement. C'est là qu'Apidog trouve sa place. C'est une plateforme API tout-en-un, de sorte que la même requête que vous envoyez à la main devient une ressource réutilisable et testable. Téléchargez Apidog pour suivre.

Voici une configuration pratique pour l'API Sonnet 5.

1. Créez la requête. Ajoutez une nouvelle requête HTTP dans Apidog. Définissez la méthode sur `POST` et l'URL sur `https://api.anthropic.com/v1/messages`. Ajoutez les en-têtes `anthropic-version: 2023-06-01` et `content-type: application/json`. Collez le corps JSON avec `"model": "claude-sonnet-5"`.

2. Stockez la clé API comme variable d'environnement. Créez un environnement (par exemple, "Anthropic Production") et ajoutez une variable nommée `ANTHROPIC_API_KEY`. Référencez-la dans l'en-tête `x-api-key` comme `{{ANTHROPIC_API_KEY}}`. Votre clé réside maintenant à un seul endroit, hors de votre corps de requête, et vous pouvez changer d'environnement sans modifier les requêtes.

3. Enregistrez-la dans une collection. Regroupez vos requêtes Sonnet 5, un appel de message simple, un appel de streaming, un appel d'outils, dans une seule collection. Toute votre équipe obtient les mêmes requêtes connues et validées au lieu de copier des extraits curl un peu partout.

4. Ajoutez un test automatisé. Joignez des assertions à la requête afin qu'une exécution échoue bruyamment quand quelque chose dérive. Par exemple :

• Affirmez que le statut de la réponse est `200`.
• Affirmez que `model` est égal à `claude-sonnet-5`.
• Affirmez que `stop_reason` est présent et non `max_tokens` (un moyen rapide de détecter la troncature après le changement de tokenizeur).
• Affirmez que `usage.output_tokens` est supérieur à `0`.

Enchaînez-les dans un scénario de test et exécutez-le en CI chaque fois que vous modifiez les prompts ou migrez les versions de modèle. Cette dernière assertion est le moyen le moins cher de détecter une régression `max_tokens` causée par l'activation par défaut de la pensée adaptative.

5. Moquez l'endpoint. Le mock intelligent d'Apidog renvoie une réponse réaliste pour la forme des Messages, de sorte que le code client de votre application, la gestion des erreurs et l'analyseur de streaming peuvent être construits et testés sans dépenser un seul jeton. C'est utile pour le travail frontend et pour les tests de charge de votre propre couche d'intégration.

Si vous passez de Postman pour cela, notre avis sur les tests API sans Postman en 2026 explique pourquoi un flux de travail conception-test-mock dans un seul outil réduit les allers-retours. Préférez-vous le terminal ? Le guide complet de l'Apidog CLI montre comment exécuter ces mêmes tests enregistrés dans un pipeline.

FAQ

Quel est l'ID du modèle Claude Sonnet 5 ?

C'est `claude-sonnet-5`, la chaîne de caractères exacte sans suffixe de date. Utilisez-le dans le champ `model` de votre requête Messages. C'est un remplacement transparent de `claude-sonnet-4-6`, donc dans la plupart des cas, vous changez l'ID du modèle et examinez trois choses : l'activation par défaut de la pensée adaptative, les paramètres d'échantillonnage supprimés et le budget de pensée manuel supprimé. Pour un aperçu complet du modèle, lisez qu'est-ce que Claude Sonnet 5.

Pourquoi ma sortie `max_tokens` est-elle tronquée sur Sonnet 5 ?

La pensée adaptative est activée par défaut, et les jetons de pensée comptent pour `max_tokens` ainsi que votre texte de réponse. Si votre plafond était réglé pour une charge de travail sans pensée sur Sonnet 4.6, augmentez-le, ou définissez `thinking: {"type": "disabled"}` si vous ne voulez pas de pensée du tout. Le nouveau tokenizeur produit environ 30 % de jetons en plus pour le même texte, ce qui aggrave l'effet.

Dois-je modifier mon code pour migrer de Sonnet 4.6 ?

Seulement à trois endroits. Supprimez les valeurs non-par défaut de `temperature`, `top_p` et `top_k`. Supprimez tout `thinking: {type: "enabled", budget_tokens: N}`. Supprimez le pré-remplissage des messages de l'assistant. Chacun de ces éléments renvoie une 400 sur Sonnet 5. Tout le reste, y compris les structures de streaming et de réponse, est inchangé. Si vous utilisez également Opus, notre guide de l'API Opus 4.8 utilise la même interface Messages.

Un refus est-il une erreur que je dois intercepter ?

Non. Un refus de cybersécurité renvoie HTTP 200 avec `stop_reason: "refusal"`. Traitez-le comme une réponse normale avec une raison d'arrêt autre que `end_turn`, et non comme une requête échouée. Ne le dirigez pas via votre chemin de nouvelle tentative en cas d'erreur.

Combien coûte l'API Sonnet 5 ?

Le prix de lancement est de 2 $ par million de jetons d'entrée et 10 $ par million de jetons de sortie jusqu'au 31 août 2026, puis 3 $ et 15 $ après cette date. Le tarif par jeton correspond à celui de Sonnet 4.6, mais le nouveau tokenizeur signifie qu'un texte équivalent peut coûter plus cher, alors mesurez avec le comptage des jetons au lieu de supposer la parité.