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.

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 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",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Quelle est la capitale de la France ?"}
    ]
)

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.

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. Pour extraire le texte :

print(message.content[0].text)

Pourquoi content[0].text ? Parce que content est une liste de blocs. Dans la plupart des cas, il n’y a qu’un seul bloc de texte, mais la structure permet aussi de renvoyer d’autres types de contenu (comme des appels d’outils) — cette liste de blocs portera plus loin dans le cours la vision, les outils et la réflexion étendue, 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",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explique-moi le concept de recursion en programmation, en 3 phrases."}
    ]
)

# Afficher la réponse
print(message.content[0].text)

# Afficher les tokens utilisés
print(f"\nTokens en entree : {message.usage.input_tokens}")
print(f"Tokens en sortie : {message.usage.output_tokens}")

# Afficher la raison d'arrêt
print(f"Raison d'arret : {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.

Points clés à retenir

• client.messages.create() est la méthode centrale du SDK
• Trois paramètres obligatoires : model, max_tokens (un plafond, pas un objectif), messages
• La réponse est dans message.content[0].text — content est une liste de blocs, structure qui resservira
• usage donne les tokens consommés ; stop_reason dit si la réponse est complète ou tronquée
• Le client se crée une fois, la clé vient de l’environnement — jamais du code

Dans la prochaine leçon, nous verrons comment gérer des conversations à plusieurs tours.