La difficulté de l'intégration de l'API Claude ne tient pas à la capacité d'envoyer une requête HTTP, mais à quelques détails faciles à manquer : dans quel en-tête placer la clé, si anthropic-version est obligatoire, pourquoi max_tokens ne peut pas être omis et pourquoi content est un tableau plutôt qu'une chaîne. Une fois ces points maîtrisés, un appel minimal peut fonctionner en une dizaine de minutes.
Cet article suit l'ordre suivant : compte et clé, en-têtes de requête, curl, Python, streaming et paramètres, dépannage des erreurs, sécurité des clés. Il explique enfin comment utiliser une passerelle compatible comme point d'entrée alternatif. Les identifiants de modèles, les contextes et la facturation sont ceux de la documentation Anthropic et de la page Tarifs des modèles.
Remarque : Anthropic et Claude sont des marques de leurs détenteurs respectifs ; OpenAI est une marque de son détenteur. Cet article n'a qu'une vocation d'explication technique. Les modèles, les prix et les quotas évoluent : vérifiez la documentation de l'éditeur avant toute intégration.
1. Préparation : compte, espace de travail et clé
L'API Claude utilise la console Anthropic pour gérer le compte, les espaces de travail, les clés API et la facturation. Avant de commencer, vérifiez trois points :
| Élément | À vérifier | Remarque |
|---|---|---|
| Compte | Adresse e-mail vérifiable, connexion à la console | Une adresse professionnelle est conseillée pour une équipe |
| Espace de travail | Espace auquel la clé appartient | L'espace détermine les membres, les clés et l'attribution de l'usage |
| Facturation | Moyen de paiement, informations de facturation, crédit disponible | Se fier à ce qu'affiche réellement la console |
Si l'équipe n'a pas encore désigné le responsable de la facturation, ne créez pas tout de suite une clé de production. Une fois une clé diffusée, l'usage et les droits sont rattachés à l'espace de travail correspondant ; la séparation ultérieure des coûts devient plus complexe.
2. Créer une clé API : six étapes
- Ouvrez la console Anthropic (console.anthropic.com), créez un compte ou connectez-vous, puis validez votre adresse e-mail.
- Créez ou sélectionnez un espace de travail. Il est recommandé de séparer production, test et expérimentation personnelle afin qu'une même clé ne serve pas partout.
- Ouvrez la page API Keys, créez une nouvelle clé et donnez-lui un nom explicite, par exemple
prod-backend-2026-10. - Copiez la clé et stockez-la immédiatement dans un gestionnaire de secrets ou une variable d'environnement. La plupart des consoles n'affichent la valeur complète qu'à la création.
- Dans la page de facturation de la console, vérifiez le moyen de paiement, les informations de facturation et les limites de crédit. La prise en charge du prépaiement, des factures et des plafonds dépend des options réellement proposées.
- Définissez la variable d'environnement en local et envoyez une requête minimale pour vérifier que la clé fonctionne.
export ANTHROPIC_API_KEY="sk-ant-votre-clé"
Ne placez jamais la clé dans le code, un dépôt Git, une page front-end ou un historique de conversation. Même en phase de test, créez une clé distincte pour pouvoir la révoquer à tout moment.
3. En-têtes et appel curl minimal
Le point d'entrée de l'API Messages est POST https://api.anthropic.com/v1/messages. Trois en-têtes sont essentiels :
| En-tête | Valeur | Rôle |
|---|---|---|
x-api-key |
Votre clé API | Authentification de la clé Anthropic |
anthropic-version |
2023-06-01 |
Version de l'API ; son absence peut provoquer une erreur |
content-type |
application/json |
Déclare un corps de requête JSON |
Attention : la clé API passe par x-api-key, et non par Authorization: Bearer. Mélanger ces deux modes d'authentification est une cause très fréquente d'erreur 401.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": "Tu es un assistant technique francophone. Réponds de manière concise.",
"messages": [
{"role": "user", "content": "Explique en trois phrases ce qu'est une passerelle API."}
]
}'
L'identifiant de modèle de l'exemple n'est que l'un des modèles actuellement disponibles. Les modèles réellement disponibles, les contextes et les prix sont ceux de l'API Models et de la page Tarifs des modèles. Dans la réponse, content est un tableau de blocs ; le texte se trouve généralement dans content[0].text, mais il est plus robuste de parcourir les blocs et de tester type == "text".
4. Appeler l'API Messages en Python
Installez le SDK :
pip install anthropic
Appel minimal :
import os
import anthropic
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
resp = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system="Tu es un assistant technique francophone. Réponds de manière concise.",
messages=[
{"role": "user", "content": "Explique en trois phrases ce qu'est une passerelle API."}
],
)
for block in resp.content:
if block.type == "text":
print(block.text)
print(resp.stop_reason)
print(resp.usage.input_tokens, resp.usage.output_tokens)
Quelques points importants :
systemest un paramètre de premier niveau : ne l'écrivez pas comme un message{"role": "system"}. Les rôles de l'API Messages sont principalementuseretassistant.max_tokensest obligatoire et fixe la longueur maximale de la réponse. Une valeur trop faible tronque la sortie etstop_reasonaffichemax_tokens; une valeur trop élevée doit être arbitrée avec le coût et les délais d'attente.resp.contentest un tableau de blocs pouvant contenir du texte, des blocs de réflexion ou des appels d'outils. Le code métier ne doit pas supposer qu'il n'y a que du texte.- Consignez
usageetstop_reason: ils servent au rapprochement de facturation et au diagnostic.
5. system, max_tokens et streaming
system contient le rôle, le format de sortie et les contraintes. Placez les contenus stables au début et les entrées utilisateur variables dans messages afin de favoriser le cache.
max_tokens ne signifie pas « plus il y en a, mieux c'est ». Il limite la sortie d'un appel sans modifier le coût d'entrée. Pour un rapport ou du code long, prévoyez une marge suffisante ; pour la classification ou l'extraction, une valeur plus faible suffit. En production, configurez-le par type d'interface plutôt qu'avec une valeur globale.
Le streaming convient aux réponses longues et aux interfaces interactives. Avec le SDK Python :
with client.messages.stream(
model="claude-opus-5-5",
max_tokens=4096,
system="Tu es un assistant technique francophone.",
messages=[{"role": "user", "content": "Rédige une description produit de 200 mots."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
Une requête en streaming renvoie aussi usage et stop_reason ; ne les oubliez pas dans la journalisation. En HTTP natif, ajoutez "stream": true au corps de la requête : la réponse est un flux d'événements SSE, à analyser notamment via content_block_delta.
6. Nommage des modèles et choix de version
Les modèles Claude se répartissent en familles Opus, Sonnet, Haiku, etc. Chaque famille a un positionnement, un contexte et un prix différents. Les identifiants existent souvent sous deux formes : un alias stable et un instantané daté. En production, choisissez explicitement l'une des formes et n'inscrivez pas le nom affiché dans la console directement dans le code.
Ordre de sélection suggéré :
- Utilisez d'abord votre jeu d'évaluation métier pour retenir la famille qui atteint le niveau de qualité requis.
- Comparez ensuite la latence, le contexte et le coût.
- Vérifiez enfin que le modèle est disponible dans la région cible et avec le mode d'accès retenu.
Les modèles sont ajoutés et retirés, et d'anciens identifiants peuvent passer en statut « legacy ». Centralisez les noms de modèles dans une configuration ou une table de correspondance pour ne modifier qu'un seul endroit lors d'une migration. Les modèles disponibles sont ceux de l'API Models, de la console et de la page Tarifs des modèles.
7. Diagnostiquer les erreurs 401, 429 et 400
| Code | Causes fréquentes | Ordre de traitement |
|---|---|---|
| 401 | Clé absente, en-tête erroné, clé révoquée, espace de travail incompatible | Vérifier x-api-key, les espaces et sauts de ligne, l'état de la clé, l'URL de base |
| 429 | Fréquence ou débit de tokens dépassé, pic de concurrence, problème de quota | Lire retry-after, appliquer un backoff exponentiel avec jitter, séparer les clés, réduire la concurrence |
| 400 | JSON invalide, max_tokens absent, identifiant de modèle erroné, paramètre hors limite |
Conserver le corps d'erreur et l'identifiant de requête, vérifier le corps champ par champ |
| 404 | Chemin ou nom de modèle inexistant | Vérifier /v1/messages et l'identifiant du modèle |
| 5xx | Défaillance temporaire en amont | Réessayer un nombre limité de fois, puis basculer vers une entrée de secours |
Lors du diagnostic, conservez d'abord l'en-tête de réponse request-id. Pour une erreur 401, ne soupçonnez pas immédiatement le solde : vérifiez prioritairement l'en-tête d'authentification et la clé elle-même. Une erreur 429 ne signifie pas forcément « plus d'argent », mais peut être une limite de débit. Une erreur 400 vient le plus souvent du corps de la requête, et le message d'erreur indique généralement le champ concerné.
8. Sécurité des clés et passerelle compatible
La sécurité des clés repose sur au moins quatre pratiques : stockage uniquement en variable d'environnement ou dans un gestionnaire de secrets ; une clé par projet ; alertes de consommation ; rotation régulière et révocation des clés des personnes qui quittent l'équipe. Aucune clé de longue durée ne doit apparaître dans un front-end, une application mobile ou un dépôt public.
Les équipes basées en Chine continentale qui rencontrent des problèmes de réseau, de paiement ou de facturation peuvent utiliser une passerelle offrant un point d'entrée compatible Anthropic à la place de l'adresse du fournisseur. Avec le SDK, il suffit généralement de modifier base_url et la clé :
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["ZSQH_API_KEY"],
base_url="https://ai.zhongshangqihang.com",
)
resp = client.messages.create(
model="selon la liste de modèles de la plateforme",
max_tokens=256,
messages=[{"role": "user", "content": "Réponds seulement OK"}],
)
print(resp.content)
Si la passerelle ne propose qu'une interface compatible OpenAI, il faut modifier la structure de la requête ou ajouter une couche d'adaptation ; changer la seule URL de base ne suffit pas. Avant de choisir une passerelle, vérifiez trois points : la prise en charge du protocole natif Anthropic, la correspondance des noms de modèles, et la transparence des politiques de limitation de débit et de journalisation.
9. Questions fréquentes
L'API Claude et l'abonnement au site Claude sont-ils la même chose ?
Non. L'abonnement au site est un produit destiné aux utilisateurs, tandis que l'API est facturée à l'usage. Les systèmes de comptes, les quotas et les interfaces de gestion sont distincts. Les clés, la facturation et l'usage de l'API sont gérés dans la console Anthropic.
Peut-on encore voir la valeur complète d'une clé après sa création ?
Dans la plupart des cas, elle n'est affichée qu'une fois, à la création. Ensuite, seul le préfixe ou le nom reste visible. Stockez donc la clé immédiatement dans un gestionnaire de secrets ; en cas de perte, révoquez l'ancienne clé et créez-en une nouvelle.
Pourquoi max_tokens est-il obligatoire ?
L'API Messages exige de déclarer explicitement la limite de sortie d'un appel pour contrôler la longueur générée et les ressources. Son omission renvoie une erreur 400. Fixez une valeur adaptée à la tâche plutôt que le maximum par défaut.
Une erreur 429 signifie-t-elle un quota épuisé ou une concurrence trop élevée ?
Les deux sont possibles. Examinez d'abord le corps de la réponse et retry-after : des erreurs concentrées sur une courte période indiquent souvent un problème de débit ou de concurrence ; si elles persistent et que le quota de facturation est anormal, vérifiez l'offre et la consommation. Les remèdes sont le backoff, la réduction de la concurrence et la séparation des clés.
Les équipes en Chine doivent-elles forcément passer par une passerelle ?
Non. Une équipe capable de se connecter directement de manière stable, d'effectuer les paiements et de mener son évaluation de conformité a souvent intérêt à utiliser l'accès direct. Envisagez une passerelle si vous avez besoin de règlement en yuans, de factures, d'un point d'entrée multi-modèles ou d'une optimisation réseau, et vérifiez alors les politiques de données et de gestion des incidents.
Pour aller plus loin
Commencez par créer un compte ZSQH AI Gateway, exécutez une requête minimale sur /v1/messages avec une clé de test, puis intégrez vos services. Les modèles, les contextes et la facturation sont indiqués sur la page Tarifs des modèles.
À lire également :
