Comment utiliser l'API Claude Sonnet 5.5 : Démarrage, optimisation, prompts, outils et streaming

Pour utiliser l'API Claude Sonnet 5.5, envoyez une requête POST à https://api.anthropic.com/v1/messages avec "model": "claude-sonnet-5-5", votre clé dans l'en-tête x-api-key, et anthropic-version: 2023-06-01. Cela coûte 2 $ par million de tokens d'entrée et 10 $ par million de tokens de sortie, lit jusqu'à 1 million de tokens de contexte, écrit jusqu'à 128K, exécute la pensée adaptative par défaut et utilise par défaut un effort high.

Anthropic a lancé Sonnet 5.5 le 28 septembre 2026 (l'article "Qu'est-ce que Claude Sonnet 5.5" couvre les spécifications et les benchmarks). Ce guide vous explique comment effectuer un premier appel en curl, Python et TypeScript, puis aborde l'effort, la pensée, les outils, le streaming, les refus et les limites de débit. Vous migrez du code Sonnet 5 ? Le guide Sonnet 5.5 vs Sonnet 5 contient toutes les modifications majeures avec JSON avant/après. Vous pouvez envoyer chaque requête ci-dessous depuis Apidog et la conserver comme test enregistré avec des assertions.

API Claude Sonnet 5.5 en un coup d'œil

Sources : la page du modèle Sonnet 5.5 et le guide de migration.

Exemple d'API Claude Sonnet 5.5 : votre premier appel

Créez une clé (le guide des clés API Anthropic vous explique comment faire) et exportez-la sous le nom ANTHROPIC_API_KEY plutôt que de la coder en dur. Envoyez ensuite ceci :

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-5",
    "max_tokens": 4096,
    "output_config": {"effort": "medium"},
    "messages": [{"role": "user", "content": "Explain idempotency keys in two sentences."}]
  }'

Le SDK Python lit ANTHROPIC_API_KEY depuis l'environnement :

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Explain idempotency keys in two sentences."}],
)
print(response.stop_reason)
for block in response.content:
    if block.type == "text":
        print(block.text)

TypeScript fonctionne de la même manière :

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 4096,
  output_config: { effort: "medium" },
  messages: [{ role: "user", content: "Explain idempotency keys in two sentences." }],
});
for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}

Lisez les blocs de contenu par type. La pensée est activée par défaut, de sorte qu'une réponse peut s'ouvrir avec un bloc thinking, et le code qui lit content[0].text peut échouer. Les tokens de pensée sont facturés comme sortie et comptent pour max_tokens même lorsque leur texte est masqué, laissez donc une marge au-delà de la réponse que vous attendez.

Choisir un niveau d'effort

L'effort, défini dans output_config.effort, est votre principal levier de coût et de qualité. Anthropic a recalibré les niveaux pour Sonnet 5.5, donc un réglage de Sonnet 5 n'est pas transférable ; effectuez un nouveau balayage sur vos propres évaluations. Le guide de prompt suggère ces points de départ :

L'éventail est large. Lors des propres exécutions de Terminal-Bench 4.0 d'Anthropic, Sonnet 5.5 a obtenu un score de 43,0 % à high pour 1,94 $ par tentative et de 70,6 % à max pour 12,54 $. La répartition des prix de Sonnet 5.5 détaille le coût par requête.

Prévoyez trois comportements. À partir de medium, le modèle réfléchit avant presque chaque réponse, même un salut, et le pousser à moins réfléchir n'est pas fiable : réduisez plutôt l'effort. Aux niveaux low et medium, il a tendance à vérifier tôt les tâches agentiques longues. Et changer l'effort de haut niveau entre les requêtes invalide le cache des prompts. Pour changer de niveau au milieu d'une conversation et conserver le cache, utilisez l'effort par message (bêta, en-tête anthropic-beta: mid-conversation-output-config-2026-07-01) : ajoutez un message role: "system" avec un content vide et le nouvel output_config.effort.

Contrôler la pensée : adaptative ou between_tools

Omettez le champ thinking et Sonnet 5.5 exécutera une pensée adaptative. Il rejette {"type": "disabled"} avec un code 400. Pour désactiver la pensée initiale, envoyez between_tools, le réglage le plus bas :

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 16000,
  "thinking": {"type": "between_tools"},
  "output_config": {"effort": "high"},
  "messages": [{"role": "user", "content": "..."}]
}

Règles pour between_tools de Sonnet 5.5 :

• Il ne fonctionne qu'avec low, medium ou high. Avec xhigh ou max, il renvoie 400.
• Il ne prend aucun autre champ. Ajouter display, budget_tokens ou block_binding renvoie 400.
• Il ne nécessite aucun en-tête bêta et fonctionne sur toutes les plateformes.
• L'effort ne peut pas changer en cours de conversation une fois qu'il est défini.
• Les versions du SDK qui ne le définissent pas échouent à la vérification de type, mettez donc à jour votre SDK.

Sous la pensée adaptative, display décide ce que contiennent les blocs de pensée. La valeur par défaut, omitted, renvoie chaque bloc thinking avec un champ thinking vide plus une signature. summarized renvoie des résumés lisibles. updates (bêta, en-tête thinking-display-updates-2026-08-18) renvoie uniquement les mises à jour de progression sous forme de texte.

Les mises à jour de progression sont le changement le plus susceptible de perturber une interface utilisateur. Sonnet 5.5 place les notes de plus d'une ou deux phrases, écrites entre les appels d'outils, dans leurs propres blocs thinking au lieu de text. Avec la valeur omitted par défaut, ces blocs sont vides, de sorte qu'une interface d'agent qui narrait auparavant ses étapes devient silencieuse. Définissez display: "updates" ou "summarized", ou exécutez between_tools, qui renvoie les notes avec du texte. Affichez chaque bloc thinking non vide avant le bloc tool_use qui le suit. Demander un raisonnement dans le texte de réponse invite à un refus reasoning_extraction, lisez donc ces blocs à la place.

Utiliser des outils sans tool_choice forcé

L'utilisation forcée d'outils a disparu. Un tool_choice de {"type": "any"} ou {"type": "tool", ...} renvoie un code 400 avec ce message, y compris sur le point de terminaison de comptage de tokens :

tool_choice: type "tool" and "any" are not supported for this model.

Envoyez auto, marquez l'outil strict: true pour que son entrée corresponde au schéma, et indiquez au modèle dans le prompt quand l'appeler :

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "input_schema": {
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"],
      "additionalProperties": false
    },
    "strict": true
  }],
  "tool_choice": {"type": "auto"},
  "messages": [{"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}]
}

Une requête peut contenir au maximum 20 outils stricts, et les schémas stricts nécessitent additionalProperties: false sur chaque objet. Sur Amazon Bedrock, les outils stricts ne sont pas disponibles pour Sonnet 5.5 : envoyez auto sans strict et validez l'entrée dans votre code.

Deux détails de boucle sont importants. Renvoyez chaque bloc thinking inchangé avec son bloc tool_use, y compris les blocs vides. Et attendez-vous à des erreurs occasionnelles de casse, telles que bash pour un outil déclaré comme Bash. Le guide de prompt suggère d'accepter les correspondances non ambiguës, ou de renvoyer un tool_result avec is_error: true qui indique le nom exact.

Diffuser les réponses (streaming)

Ajoutez "stream": true au corps de la requête, ou utilisez l'aide au streaming du SDK. Pour le codage agentique, le guide de prompt recommande un max_tokens de 128 000 avec streaming :

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=128000,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Review this diff for bugs: ..."}],
) as stream:
    for event in stream:
        if event.type == "content_block_delta" and event.delta.type == "text_delta":
            print(event.delta.text, end="", flush=True)
    final = stream.get_final_message()

Les événements envoyés par le serveur arrivent sous forme de message_start, puis content_block_start, content_block_delta et content_block_stop pour chaque bloc, puis message_delta (portant stop_reason) et message_stop. Sous omitted, un bloc de pensée diffuse un thinking_delta vide et un signature_delta, puis le texte commence. Attendez-vous à une pause de plusieurs secondes avant l'ouverture d'un bloc de mise à jour de progression.

stream.get_final_message() (TypeScript : stream.finalMessage()) reconstruit des blocs complets avec leurs signatures. Ajoutez ce contenu à l'historique en tant que tour de l'assistant, inchangé, et maintenez l'historique en mode ajout uniquement. Sonnet 5.5 signe chaque bloc de pensée sur la conversation qui le précède, donc sur les comptes créés le ou après le 31 août 2026 (00:00 UTC), rejouer un bloc après avoir modifié l'historique antérieur renvoie 400. Les blocs sont également liés au compte qui les a produits.

Gérer les refus et les replis (fallback)

Un refus n'est pas une erreur. Vous recevez un HTTP 200 avec stop_reason: "refusal" et un objet stop_details dont la category est cyber, bio, frontier_llm, reasoning_extraction ou general_harms, plus une explanation. Affichez l'explication plutôt que de l'analyser ; sa formulation n'est pas stable. Traitez stop_reason avant de lire content.

Le repli côté serveur est optionnel. Ajoutez "fallbacks": "default" et l'en-tête anthropic-beta: server-side-fallback-2026-07-01 (bêta, API Claude uniquement), et l'API réessaie les refus cyber et frontier_llm sur Sonnet 5. Les trois autres catégories ne sont pas réessayées. Le champ model de la réponse nomme le modèle qui l'a servie, et un bloc de contenu fallback marque le transfert.

Limites de débit

Sonnet 5.5 a sa propre limite de débit, distincte de celle de Sonnet 5. La page des limites de débit liste quatre niveaux :

Pour la gestion des erreurs 429 et le backoff, consultez le guide sur le dépassement des limites de débit.

Tester l'API Claude Sonnet 5.5 dans Apidog

Les requêtes enregistrées rendent les comparaisons d'efforts et le débogage de flux reproductibles. Voici la configuration dans Apidog :

1. Créez un environnement et ajoutez ANTHROPIC_API_KEY comme variable. Référencez-la comme {{ANTHROPIC_API_KEY}} dans l'en-tête x-api-key, à côté de anthropic-version et content-type.
2. Créez une requête POST vers https://api.anthropic.com/v1/messages, collez le corps du premier appel et enregistrez-la.
3. Ajoutez des assertions : le statut est 200, $.stop_reason est égal à end_turn, $.usage.output_tokens est supérieur à 0, et $.content[*].type contient text. Un refus fait maintenant échouer le test au lieu de le passer silencieusement.
4. Dupliquez la requête avec "stream": true. Apidog affiche la réponse text/event-stream événement par événement, afin que vous puissiez voir arriver dans l'ordre le thinking_delta vide, le signature_delta et le texte.
5. Clonez-la à nouveau avec "model": "claude-sonnet-5" et conservez la paire dans un seul dossier : même prompt, deux modèles, usage côte à côte.

Pour des modèles plus larges, consultez le test des applications LLM et le test des API d'agents IA.

FAQ

Quel est l'ID du modèle Claude Sonnet 5.5 ? claude-sonnet-5-5, sans suffixe de date, sur l'API Claude, Google Cloud, Microsoft Foundry et Claude Platform sur AWS. Sur Amazon Bedrock, c'est anthropic.claude-sonnet-5-5.

Puis-je désactiver complètement la pensée ? Non. disabled renvoie 400. between_tools est le réglage le plus bas : pas de pensée initiale, avec un effort low, medium ou high.

Pourquoi ma requête Sonnet 5 renvoie-t-elle 400 sur Sonnet 5.5 ? Vérifiez d'abord la présence de thinking.type: "disabled" et d'un tool_choice forcé. Le guide Sonnet 5.5 vs Sonnet 5 couvre les cinq changements majeurs et leurs correctifs.

Existe-t-il une API Claude Sonnet 5.5 gratuite ? L'API d'Anthropic est prépayée, et aucune page officielle n'indique de crédit d'inscription gratuit. Un plan de chat Claude n'inclut pas non plus l'accès à l'API. Le guide de l'API gratuite couvre les programmes de crédit et le chemin payant le moins cher.

Prochaine étape

Envoyez la requête du premier appel avec un effort medium, puis réexécutez-la avec un effort high et comparez les usage.output_tokens et la qualité de la réponse sur un prompt de votre propre charge de travail. Téléchargez Apidog pour enregistrer les deux exécutions avec des assertions. Si vous préférez travailler depuis le terminal, consultez Claude Sonnet 5.5 dans Claude Code.