Votre première requête

La clé API est en place : passons à la pratique. Dans cette leçon, vous allez envoyer votre première requête à Claude via l’API — et rencontrer les trois paramètres qui reviendront dans chaque appel du cours.

Installation

Installez les deux packages nécessaires :

pip install anthropic python-dotenv

Le premier est le SDK officiel d’Anthropic, le second lit votre fichier .env : le duo standard de tous nos exemples. Le cours officiel installe "anthropic<1", une ancienne version du SDK ; nous utilisons la version actuelle (2.x), qui demande Python 3.10 ou plus.

Configuration

Assurez-vous que votre fichier .env contient votre clé :

# .env
ANTHROPIC_API_KEY=sk-ant-api03-votre-cle-ici

Créer le client

from dotenv import load_dotenv
import anthropic

load_dotenv()

client = anthropic.Anthropic()

Le cours officiel range aussi le nom du modèle dans une variable, model, pour le changer en un seul endroit ; nous ferons de même à partir de la leçon suivante. Le SDK détecte automatiquement la variable d’environnement ANTHROPIC_API_KEY — pas besoin de la passer explicitement, et votre code ne contient donc jamais le secret. Ce client sera créé une fois et réutilisé pour toutes les requêtes.

Envoyer une requête

La méthode principale est client.messages.create(). Elle prend trois paramètres obligatoires :

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Qu'est-ce que l'informatique quantique ? Réponds en une phrase."}
    ]
)

Les trois paramètres obligatoires

Un mot sur max_tokens, souvent mal compris : c’est un plafond de sécurité, pas un objectif. Claude s’arrête quand sa réponse est finie ; la limite ne sert qu’à borner les réponses qui s’éterniseraient, et votre facture avec. Sur les modèles actuels, qui réfléchissent avant de répondre, la réflexion compte dans ce plafond : laissez de la marge, ici 4 096 tokens.

La structure d’un message

Chaque message est un dictionnaire avec deux champs :

• role : soit "user" (vous), soit "assistant" (Claude)
• content : le texte du message

Notre liste n’a qu’un message pour l’instant — le strict minimum — mais cette structure de liste est la clé de tout ce qui suit : c’est en y accumulant les tours qu’on construira de vraies conversations.

Lire la réponse

La réponse est un objet Message. Son attribut content est une liste de blocs ; pour extraire le texte, on garde les blocs de type text :

print("".join(block.text for block in message.content if block.type == "text"))

Le cours officiel écrit message.content[0].text, qui fonctionne avec Claude Haiku 4.5 tant qu’il ne réfléchit pas. Avec Sonnet 5.5, qui réfléchit par défaut, le premier bloc peut être un bloc thinking, sans attribut text : ce raccourci plante. Cette liste de blocs portera plus loin dans le cours la réflexion, les outils et la vision, sans jamais changer de forme.

Exemple complet

from dotenv import load_dotenv
import anthropic

load_dotenv()

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Explique-moi le concept de récursion en programmation, en 3 phrases."}
    ]
)

# Afficher la réponse (blocs de texte seulement)
print("".join(block.text for block in message.content if block.type == "text"))

# Afficher les tokens utilisés (la sortie inclut la réflexion)
print(f"\nTokens en entrée : {message.usage.input_tokens}")
print(f"Tokens en sortie : {message.usage.output_tokens}")

# Afficher la raison d'arrêt
print(f"Raison d'arrêt : {message.stop_reason}")

Les dernières lignes méritent le coup d’œil : usage donne les tokens consommés — la matière première de votre facturation, à surveiller dès maintenant — et stop_reason explique pourquoi la génération s’est arrêtée : end_turn pour une réponse complète, max_tokens pour une réponse tronquée par le plafond. Vérifier ce champ est le réflexe qui détecte les réponses coupées.

Explorer la réponse complète

Pour voir la structure complète de la réponse :

print(message)

Vous verrez tous les champs : id, type, role, content, model, stop_reason, usage. Prenez une minute pour les regarder une fois : savoir ce que l’API renvoie vraiment évite bien des surprises. Repérez en particulier si content commence par un bloc thinking.

À vous de jouer

Votre première requête. Reprenez l’exemple complet avec une question de votre métier. Lancez-le trois fois : la réponse change-t-elle ? Le nombre de tokens de sortie aussi ? Notez si content contient un bloc thinking.

Changer de modèle. Remplacez claude-sonnet-5-5 par claude-haiku-5-5, puis par claude-opus-5-5, et comparez la réponse, les tokens et le temps d’attente.

Sources officielles : Making a request (Claude Academy) · Get started with Claude et Create a Message (documentation Claude)

Points clés à retenir

• client.messages.create() est la méthode centrale du SDK ; le client se crée une fois, la clé vient de l’environnement.
• Trois paramètres obligatoires : model, max_tokens (un plafond, réflexion comprise), messages.
• content est une liste de blocs : on lit les blocs text, pas content[0].text.
• usage donne les tokens consommés ; stop_reason dit si la réponse est complète ou tronquée.