+190 XP

Claude · L'API Messages : vos premiers vrais appels

C'est dans la fenêtre de chat que vous avez appris Claude. C'est avec l'API Messages que vous le mettez au travail : le même modèle, sans interface. Vous envoyez une requête structurée, vous recevez une sortie structurée, et vous le faites depuis votre propre code, à votre rythme, dans votre propre produit.

Vous avez déjà fait un « premier appel d'API » générique, donc cette leçon saute les préliminaires et couvre ce qui est propre à Claude : la forme de la requête, pourquoi le prompt system se trouve là où il est, comment obtenir des formats fiables, et comment streamer les réponses longues pour que vos utilisateurs ne fixent pas un écran vide.

La forme d'une requête Claude

Chaque appel à l'API Messages se compose de quelques éléments :

  • model : le Claude que vous voulez (une variante Sonnet, Opus ou Haiku). Sonnet est le modèle de travail courant, Opus le plus capable pour le raisonnement difficile, et Haiku le plus rapide et le moins cher.
  • max_tokens : le plafond du nombre de tokens que Claude peut générer dans sa réponse. C'est une borne supérieure, pas une cible. Il ne rallonge pas la réponse, il la plafonne seulement.
  • messages : la conversation, sous forme de liste de tours. Chaque tour a un role (user ou assistant) et un content.
  • system (facultatif mais important) : un paramètre de premier niveau, distinct de la liste des messages. Le rôle, le ton et les règles vont ici.

Ce dernier point piège ceux qui viennent d'autres API. Dans l'API Messages, le prompt système n'est pas un message avec role: "system". C'est un champ à part entière de la requête. Les modèles d'Anthropic sont entraînés autour de cette structure, et placer les instructions permanentes dans system plutôt que de les glisser dans un tour utilisateur fait que Claude les suit de façon plus fiable.

Pour rappel, un token est le fragment de texte que le modèle lit et écrit (quelques caractères environ). Vous payez par token en entrée et par token en sortie, donc max_tokens sert aussi à maîtriser les coûts.

Votre premier vrai appel

Voici un appel complet et exécutable. Installez d'abord le SDK avec pip install anthropic et définissez votre clé dans la variable d'environnement ANTHROPIC_API_KEY.

python
import anthropic

client = anthropic.Anthropic()  # lit ANTHROPIC_API_KEY depuis l'environnement

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a precise release-notes editor. Reply in tight bullet points.",
    messages=[
        {
            "role": "user",
            "content": "Summarize: we shipped SSO, fixed a billing bug, and removed the legacy export.",
        }
    ],
)

print(response.content[0].text)

Regardez maintenant ce qui revient. La réponse est un objet, pas une chaîne brute. Son content est une liste de blocs de contenu, car une même réponse peut contenir plusieurs types de blocs (du texte et, plus tard, des demandes d'utilisation d'outils). Pour une réponse texte simple, vous lisez response.content[0].text. Vous obtenez aussi response.usage, avec le nombre de tokens en entrée et en sortie, et response.stop_reason, qui vous indique *pourquoi* Claude s'est arrêté. end_turn signifie qu'il a terminé normalement. max_tokens signifie qu'il a atteint votre plafond et a été coupé. Vérifiez toujours stop_reason en production : une réponse tronquée que vous avez traitée comme complète est un bug silencieux.

Les identifiants de modèles évoluent avec le temps, donc vérifiez les noms et paramètres actuels dans la référence officielle de l'API Messages avant de mettre en production.

C'est à vous de porter la conversation

L'API est sans état. Claude ne se souvient pas de votre appel précédent. C'est *vous* qui tenez la conversation, en ajoutant chaque tour à la liste messages et en renvoyant l'ensemble.

Un échange en plusieurs tours n'est qu'une liste :

python
messages = [
    {"role": "user", "content": "What's a good index for a time-series table?"},
    {"role": "assistant", "content": "Start with a composite index on (device_id, ts)."},
    {"role": "user", "content": "Why that order and not (ts, device_id)?"},
]

Faites alterner les tours entre user et assistant. Si vous envoyez deux tours user d'affilée, l'API les fusionne en un seul, ce qui fonctionne mais rend votre historique plus difficile à suivre. Traitez la liste comme la vraie transcription et ajoutez la réponse de Claude après chaque appel.

Obtenir un format fiable

Les anciens guides enseignent le prefilling : terminer la liste messages par un tour assistant partiel (par exemple {) pour que Claude continue à partir de là. Ne construisez pas là-dessus. Les modèles Claude les plus récents rejettent avec une erreur un dernier tour assistant prérempli, et la technique n'a jamais été qu'un contournement.

Vous avez désormais de meilleures options :

  • Pour un JSON garanti, utilisez les structured outputs : vous passez un schéma JSON avec la requête et la réponse est contrainte de s'y conformer. Consultez le guide des structured outputs pour le paramètre exact.
  • Pour un contrôle de format plus léger, indiquez le format dans system (« Reply with exactly three bullets, no preamble ») et montrez un court exemple.
  • L'utilisation d'outils avec un schéma d'entrée défini est une autre façon solide d'obtenir des champs typés, traitée plus loin dans ce module.

Le streaming pour les réponses longues

Quand Claude rédige une longue réponse, vous ne voulez pas attendre qu'elle soit entièrement générée pour afficher quoi que ce soit. Le streaming renvoie la réponse par morceaux au fil de leur génération, si bien que le texte apparaît mot par mot, comme dans l'application Claude.

Changez une méthode et itérez :

python
with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system="You are a technical writer. Be concrete.",
    messages=[{"role": "user", "content": "Explain database connection pooling."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final = stream.get_final_message()
    print("\n\nTokens used:", final.usage.output_tokens)

La méthode stream() renvoie un gestionnaire de contexte (le bloc with), qui ferme proprement la connexion même si quelque chose échoue en cours de stream. Le helper text_stream ne vous transmet que les deltas de texte, ce qui est généralement ce qu'il faut pour une interface. À la fin de la boucle, get_final_message() reconstitue la réponse complète, et vous récupérez donc toujours usage et stop_reason.

Streamez dès qu'une réponse risque d'être longue ou qu'un humain la regarde arriver. Pour les tâches courtes en arrière-plan où rien n'attend la sortie, l'appel create() simple est plus facile et tout aussi rapide au total.

Ce qui est propre à Claude

Quelques comportements méritent d'être connus avant de construire dessus.

Les prompts système pèsent réellement. Les instructions permanentes placées dans system sont suivies plus régulièrement que le même texte enfoui dans un message utilisateur. Mettez ce qui est durable (rôle, format de sortie, contraintes strictes) dans system, et la tâche propre à chaque requête dans le tour utilisateur.

Le contexte long est utilisable en pratique. Les modèles Claude prennent en charge de grandes fenêtres de contexte, assez pour des documents entiers, de longues transcriptions ou une bonne partie d'une base de code, donc vous pouvez souvent passer directement le matériau source au lieu de construire un système de retrieval. Les prix et tailles de fenêtre évoluent, donc vérifiez les chiffres actuels dans la documentation plutôt que de les mémoriser.

La même API alimente les outils et les agents. L'utilisation d'outils, les connecteurs exposés par les applications Claude, les serveurs MCP et le Claude Agent SDK reposent tous sur cet appel messages.create. L'utilisation d'outils, ce sont simplement des types de blocs de contenu supplémentaires qui circulent dans la forme de requête et de réponse que vous connaissez déjà.

Vérification des acquis

1. Dans l'API Messages, comment faut-il fournir les instructions permanentes sur le rôle, le ton et les règles ?

2. Que contrôle réellement le paramètre max_tokens ?

3. Selon la leçon, quelle variante de Claude est présentée comme le modèle de travail courant ?

CHOIX MULTIPLES

4. Sélectionnez TOUTES les affirmations vraies sur les éléments requis ou importants d'une requête à l'API Messages de Claude.

Sélectionnez toutes les réponses correctes.

CHOIX MULTIPLES

5. Sélectionnez TOUTES les affirmations correctes sur les tokens et le coût dans l'API Messages.

Sélectionnez toutes les réponses correctes.

Lire les erreurs et être un bon client

Les vrais appels échouent parfois. Voici ceux que vous rencontrerez en premier :

  • 401 (authentification) : votre ANTHROPIC_API_KEY est absente, erronée ou non chargée dans l'environnement. Vérifiez que la variable est définie (sans afficher la clé elle-même).
  • 429 (limite de débit) et 529 (surcharge) : vous envoyez trop vite, ou le service est momentanément saturé. La solution est la même dans les deux cas : ralentissez et réessayez.

Le SDK réessaie déjà certains échecs avec un backoff exponentiel, mais vous devez quand même encapsuler vos appels et gérer les cas où le SDK abandonne :

python
import anthropic

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        messages=[{"role": "user", "content": "One sentence on idempotency."}],
    )
    print(response.content[0].text)
except anthropic.RateLimitError:
    print("Rate limited. Slow down and retry with backoff.")
except anthropic.APIStatusError as exc:
    print(f"API error {exc.status_code}: {exc.message}")

Interceptez spécifiquement RateLimitError quand vous voulez un backoff personnalisé, et rabattez-vous sur APIStatusError pour tout autre statut d'échec. C'est la différence entre un script qui meurt au premier accroc et un service qui tient un après-midi chargé.

Où conserver vos clés

Celle-ci piège les gens dès le premier jour. Votre clé d'API est un secret auquel est rattachée la facturation. Ne la codez jamais en dur dans le source, ne la commitez jamais, et ne la livrez jamais dans une application navigateur où les utilisateurs peuvent la lire. Gardez-la dans une variable d'environnement ou un gestionnaire de secrets. Le constructeur anthropic.Anthropic() récupère ANTHROPIC_API_KEY sans argument, c'est pourquoi tous les extraits ci-dessus la laissent implicite. Si vous avez besoin d'appels côté navigateur, faites-les passer par un petit backend qui détient la clé.

Vous pouvez générer et renouveler vos clés dans la Claude Console, et le code source du SDK se trouve sur github.com/anthropics si vous voulez voir comment les nouvelles tentatives et le streaming sont implémentés.

Points clés

  • Placez les instructions permanentes dans le paramètre system de premier niveau, pas dans un message utilisateur. Réservez les tours utilisateur à la tâche elle-même.
  • Vérifiez toujours stop_reason et usage. Une réponse coupée à max_tokens paraît complète mais ne l'est pas, et le nombre de tokens est votre indicateur de coût.
  • L'API est sans état : portez vous-même la conversation et faites alterner les tours.
  • Oubliez le prefilling sur les modèles actuels. Utilisez les structured outputs quand vous avez besoin d'un JSON garanti.
  • Utilisez messages.stream() avec text_stream quand un humain attend, et create() pour les tâches silencieuses en arrière-plan.
  • L'utilisation d'outils, les connecteurs, MCP et l'Agent SDK passent tous par cette même forme de requête et de réponse.

À faire, tiré de cette leçon

Ces actions sont compilées dans le plan d'action du rôle.

  • Placez les instructions permanentes dans le paramètre `system` de premier niveau de l'API
  • Vérifiez systématiquement stop_reason et usage dans chaque réponse de l'API
  • Streamez les réponses dès qu'un humain attend l'output
Voir le plan d'action complet →