Guide de l'API Claude Sonnet 5 : clé, contexte et appels (2026)

Claude Sonnet 5 est le modèle Sonnet publié par Anthropic le 30 juin 2026, avec trois arguments principaux : un contexte d'un million de jetons, une réflexion adaptative et une stabilité pensée pour les agents. Un état doit être précisé d'emblée : en octobre 2026, Sonnet 5.5 est le modèle Sonnet courant, et Sonnet 5 est passé en statut legacy tout en restant disponible, avec une promesse de retrait pas avant le 30 juin 2027. Les nouveaux projets devraient évaluer Sonnet 5.5 en priorité ; les équipes déjà sur claude-sonnet-5 doivent maîtriser les détails de clé, de contexte et d'appel pour éviter les problèmes avant une migration.

Cet article couvre l'état du modèle, l'obtention de clé, les appels Messages API, les limites d'usage du contexte 1M, le cache et la maîtrise des coûts, puis les erreurs courantes et les questions fréquentes.

Remarque : Anthropic et Claude sont des marques de leurs détenteurs respectifs ; cet article est purement technique. Les spécifications, contextes et règles de facturation sont celles de la documentation officielle Anthropic et de la page Tarifs des modèles ; nous ne figeons aucun prix unitaire.

1. Vérifier l'état et les spécifications du modèle

Élément	Information officielle
Identifiant	`claude-sonnet-5`
Statut	Legacy, toujours disponible
Date de publication	30 juin 2026
Engagement de retrait	Pas avant le 30 juin 2027
Fenêtre de contexte	1 000 000 de jetons
Sortie maximale	128 000 jetons (Messages API synchrone)
Sortie par lots	300 000 jetons (Batch API bêta)
Entrée/sortie	Texte, images → texte
Mode de réflexion	Réflexion adaptative, effort par défaut high
Fin de connaissances	Janvier 2026

Quelques points souvent mal compris :

« Legacy » ne signifie pas « retiré ». Cela indique qu'un modèle plus récent existe, mais l'ancien reste pris en charge pendant sa période de service.
Un contexte de 1M est une capacité, pas un objectif. Plus le contexte est long, plus le coût d'entrée et la latence augmentent.
La réflexion adaptative est active par défaut ; sur une tâche simple, effort permet d'en réduire la profondeur.
L'interface synchrone plafonne la sortie à 128K ; au-delà, envisagez la capacité bêta de la Batch API.

Pour un nouveau projet parti de zéro, évaluez directement Sonnet 5.5. Si vos prompts, jeux d'évaluation et trafic de production reposent déjà sur Sonnet 5, comparez d'abord sur un faible volume avant de fixer la date de migration.

2. Obtenir une clé API Claude

Voie 1 : Anthropic Console

Inscrivez-vous et connectez-vous à Anthropic Console, puis configurez l'organisation et la facturation.
Créez une clé depuis la page API Keys, nommée selon le projet ou l'environnement.
Vérifiez le solde, les limites de débit et les permissions du modèle.
Stockez la clé dans une variable d'environnement serveur ; jamais dans le frontend ni dans Git.

L'URL de base officielle est https://api.anthropic.com et le chemin Messages est /v1/messages.

Voie 2 : ZSQH AI Gateway

Créez un compte sur ZSQH AI Gateway, générez une clé, rechargez et facturez en yuan, et consultez dans une seule console l'usage de plusieurs modèles. La passerelle fournit une entrée compatible Anthropic, avec l'URL de base https://ai.zhongshangqihang.com et le même chemin /v1/messages. Les modèles Claude activés et le nom exact à utiliser sont indiqués sur la page Tarifs des modèles.

Élément	Connexion directe Anthropic	Passerelle ZSQH
URL de base	`https://api.anthropic.com`	`https://ai.zhongshangqihang.com`
En-tête d'authentification	`x-api-key`	`x-api-key`
En-tête de version	`anthropic-version: 2023-06-01`	Identique
Nom du modèle	`claude-sonnet-5`	Selon la page de tarifs du site
SDK	SDK Anthropic	SDK Anthropic

3. Appel en curl

export ANTHROPIC_API_KEY="sk-votre-clé"

curl "https://ai.zhongshangqihang.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": 800,
    "system": "Vous êtes un éditeur technique francophone ; vos réponses doivent être concrètes.",
    "messages": [
      {"role": "user", "content": "Expliquez en trois points les limites d’usage d’un contexte de 1M."}
    ]
  }'

Trois points d'attention : max_tokens est obligatoire dans l'API Messages de Claude ; l'authentification utilise x-api-key et non Authorization: Bearer ; l'en-tête anthropic-version est indispensable. L'absence de l'un de ces éléments produit un 401 ou un 400.

4. Appel en Python

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://ai.zhongshangqihang.com",
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="Vous êtes un assistant de contrôle qualité du service client ; sortez uniquement du JSON.",
    messages=[
        {"role": "user", "content": "Évaluez le sentiment : livraison trop lente, mais bon accueil du support."}
    ],
)

print(msg.content[0].text)

Un changement de compatibilité à connaître absolument : Sonnet 5 renvoie un 400 si temperature, top_p ou top_k reçoit une valeur non par défaut. Autrement dit, si votre ancien code contient temperature=0.2 par habitude, retirez-le lors de la migration et pilotez la stabilité de sortie par le prompt et effort.

5. Utiliser le contexte 1M à bon escient

Un million de jetons représente environ 550 000 mots anglais ou 2,5 millions de caractères Unicode, selon les estimations du tokenizer officiel actuel. Cela convient aux scénarios où l'on veut « placer tout le dossier d'un coup », mais pas à l'envoi indifférencié de toutes les ressources.

Scénario	Pratique recommandée	Raison
Revue de contrat long	Envoyer le texte entier et demander un JSON par clause	Éviter qu'une clause clé échappe à la recherche
Questions sur un dépôt de code	Rechercher d'abord les fichiers pertinents, puis assembler le contexte	Tout le code coûte cher et disperse l'attention
Service client multi-tours	Garder les derniers tours et un résumé de l'historique	Limiter la croissance de l'entrée
Analyse hors ligne en volume	Utiliser la Batch API	Remise dédiée officielle pour les lots
Génération de rapports longs	Générer par sections puis fusionner	Éviter d'atteindre le plafond de sortie

La priorité de gestion du contexte est : recherche d'abord, résumé ensuite, texte intégral en dernier. Le contexte intégral ne vaut le supplément que lorsque « manquer un passage peut provoquer une erreur ».

6. Cache et maîtrise des coûts

La facturation de Claude comprend l'entrée, la sortie, l'écriture du cache et la lecture du cache. Selon la page de tarifs officielle, la lecture du cache représente environ un dixième du prix d'entrée, l'écriture d'un cache de 5 minutes environ 1,25 fois le prix d'entrée, et l'écriture d'un cache d'une heure davantage encore ; la Batch API facture entrée et sortie à moitié prix. Les prix exacts sont ceux de la page Tarifs des modèles.

Coût d'une requête =
  jetons d'entrée non mis en cache × prix d'entrée
+ jetons écrits dans le cache × prix d'écriture du cache
+ jetons lus dans le cache × prix de lecture du cache
+ jetons de sortie × prix de sortie

La maîtrise des coûts suit cet ordre :

Stabiliser le préfixe cache : placer prompt système, définitions d'outils et base de connaissances fixe au début, avec cache_control.
Ne cacher que le contenu réutilisé : un document à usage unique ne doit pas être mis en cache, sous peine de payer l'écriture pour rien.
Rechercher avant d'envoyer le texte intégral : une récupération RAG de 5 à 10 extraits coûte généralement moins que la base entière.
Confier les tâches hors ligne à Batch : annotation, résumé et classification sans temps réel passent en priorité par des lots.
Ajuster effort : réduire la profondeur de réflexion sur les tâches simples, l'augmenter sur les tâches complexes.
Limiter la sortie : définir max_tokens et exiger une sortie structurée pour éviter les longs textes inutiles.
Séparer les clés par projet : plafonds et alertes, avec une revue hebdomadaire du classement des consommations.

7. Erreurs courantes

Erreur	Cause fréquente	Traitement
`401 Unauthorized`	Clé erronée, `x-api-key` absent	Recopier la clé, vérifier l'en-tête
`404 Not Found`	URL de base ou chemin incorrect	Vérifier `/v1/messages`
`400 invalid_request_error`	Valeur non par défaut de `temperature`, etc.	Retirer le paramètre et réessayer
`429 rate_limit_error`	Concurrence ou fréquence dépassée	Réduire la concurrence, délai exponentiel
`529 overloaded_error`	Charge serveur trop élevée	Réessayer plus tard, prévoir un canal de secours
`invalid_request_error` (prompt is too long)	Entrée au-delà de 1M	Découper, rechercher ou résumer
Erreur liée à `max_tokens`	Champ absent ou au-delà de la limite	Renseigner selon les spécifications du modèle

Questions fréquentes

Faut-il migrer de Sonnet 5 vers Sonnet 5.5 ?

Ce n'est pas obligatoire. Sonnet 5 reste dans sa période de service, avec un retrait prévu pas avant le 30 juin 2027. Les nouveaux projets devraient toutefois évaluer Sonnet 5.5 en priorité ; pour l'existant, comparez d'abord sur un faible volume et vérifiez la compatibilité des prompts, des appels d'outils et des formats de sortie avant de migrer.

La clé API Claude fonctionne-t-elle avec l'abonnement Claude ?

Non. L'abonnement concerne le site web et les applications clientes ; la clé API est un identifiant développeur, avec facturation et permissions séparées.

Le contexte 1M coûte-t-il plus cher ?

Oui. La capacité de contexte n'est pas facturée séparément, mais plus l'entrée contient de jetons, plus la facture et la latence augmentent. Pour les documents longs, privilégiez la recherche et le résumé ; n'utilisez le contexte complet que lorsque le jugement exige tout le texte.

Sonnet 5 accepte-t-il les images en entrée ?

Oui, la spécification officielle est entrée texte et images, sortie texte. Les images sont converties en jetons d'entrée selon des règles définies ; estimez le coût avant un traitement en volume.

Pourquoi définir `temperature` provoque-t-il un 400 ?

Sonnet 5 n'accepte pas de valeur non par défaut pour temperature, top_p ou top_k. Retirez ces paramètres et pilotez la sortie par le prompt et effort.

Et ensuite

Créez d'abord une clé de test sur ZSQH AI Gateway, validez une requête Messages en curl, puis intégrez le SDK Anthropic. La disponibilité des modèles et les prix sont indiqués sur la page Tarifs des modèles.