Comment démarrer avec l’API Claude en Python ?

Il faut installer le SDK Anthropic, sécuriser sa clé API, puis appeler client.messages.create avec un modèle, max_tokens et un message user. Le vrai sujet vient juste après : lire proprement la réponse, cadrer Claude avec un prompt système et streamer les sorties sans bricoler.

De quoi ai-je besoin ?

J’ai besoin de peu de choses, mais je préfère les poser proprement dès le départ. Il me faut Python 3.9 ou plus, un accès à la Claude Console, une clé API Anthropic, et le SDK Python officiel, c’est-à-dire la librairie fournie par Anthropic pour appeler Claude sans bricoler les requêtes HTTP à la main.

J’installe le SDK avec pip install anthropic. Je ne mets jamais une clé API en dur dans le code. Vraiment jamais. C’est le genre de raccourci qui finit mal en prod, dans un repo Git oublié, ou dans un vieux notebook partagé trop vite avec un client. La bonne pratique, c’est de passer par une variable d’environnement appelée ANTHROPIC_API_KEY. Le SDK Anthropic sait la lire automatiquement.

Voilà la base propre que j’utilise généralement :

pip install anthropic

Sur macOS ou Linux, je définis la variable comme ça :

export ANTHROPIC_API_KEY="votre_cle_api_ici"

Sur Windows avec PowerShell, l’équivalent ressemble à ça :

$env:ANTHROPIC_API_KEY="votre_cle_api_ici"

Ensuite, je peux créer le client Anthropic sans lui passer la clé directement :

from anthropic import Anthropic

client = Anthropic()

message = client.messages.create(
    model="claude-3-5-sonnet-latest",
    max_tokens=200,
    messages=[
        {"role": "user", "content": "Bonjour Claude"}
    ],
)

print(message.content)

Si le projet tourne en local, j’utilise parfois un fichier .env avec python-dotenv. Ça évite de retaper la variable à chaque session, sans salir le code. Il faut juste penser à ajouter .env dans .gitignore. J’ai déjà vu des clés partir sur GitHub comme ça, et personne n’a envie de dépenser du budget API pour des inconnus.

pip install python-dotenv

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()

client = Anthropic()

L’objectif, à ce stade, c’est simple. Avoir une base saine avant même de parler de prompt.

Élément	À quoi ça sert	Piège à éviter
Python	Faire tourner le script, en version 3.9 ou plus.	Utiliser une vieille version qui casse les dépendances.
Compte Claude Console	Créer et gérer l’accès à l’API Claude.	Confondre l’app Claude classique avec la console API.
Clé API	Authentifier les appels vers Anthropic.	La coller directement dans le code.
SDK Anthropic	Appeler Claude proprement depuis Python.	Réinventer les appels HTTP sans raison.
Variable d’environnement	Stocker la clé hors du code avec ANTHROPIC_API_KEY.	Oublier de la configurer avant de lancer le script.

Comment faire le premier appel ?

Le premier appel à l’API Claude se fait avec client.messages.create. Je passe au minimum trois choses : model, max_tokens et messages. Sans ça, vous n’avez pas encore une vraie requête exploitable.

La logique de l’API Messages est assez simple. Vous envoyez une liste de messages à Claude. Chaque message a un rôle et un contenu. En général, on commence avec un rôle user, parce que c’est vous qui posez la première question.

Les trois paramètres de base ont chacun un rôle précis :

• model indique le modèle Claude à utiliser. L’identifiant doit être exact, caractère par caractère, sinon l’appel échoue.
• max_tokens fixe le plafond de sortie. Ce n’est pas une promesse de qualité. C’est juste une limite. Si elle est trop basse, la réponse peut être coupée au milieu.
• messages contient la conversation envoyée au modèle, sous forme de liste avec des rôles et du texte.

Voilà un exemple Python complet et minimal, sans framework autour. Il suppose juste que votre clé API est chargée dans la variable d’environnement ANTHROPIC_API_KEY.

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=300,
    messages=[
        {
            "role": "user",
            "content": "Définis simplement ce qu'est une context window dans un modèle de langage."
        }
    ]
)

text = response.content[0].text
print(text)

La ligne importante à la fin, c’est response.content[0].text. La réponse de Claude revient sous forme de blocs de contenu. Ici, on récupère simplement le premier bloc texte. Pour un premier test, c’est largement suffisant.

Sur les premiers prototypes clients, je vois souvent les mêmes erreurs. Un nom de modèle mal copié. Une clé API pas chargée dans l’environnement. Un max_tokens mis à 20, puis quelqu’un pense que Claude répond mal alors qu’il est juste coupé trop tôt. Avant de chercher compliqué, je vérifie toujours ces trois points. Ça évite pas mal de fausses pistes.

Que contient la réponse ?

L’appel retourne un objet typé Message, pas juste une chaîne de texte. C’est un détail important, parce que la réponse contient le texte généré, oui, mais aussi des métadonnées très utiles pour comprendre ce qui s’est passé.

Dans cet objet, je regarde surtout ces champs :

• id : L’identifiant unique de la réponse.
• type : Le type d’objet retourné, généralement message.
• role : Le rôle de l’émetteur, souvent assistant.
• content : Le contenu généré par Claude.
• model : Le modèle utilisé pour générer la réponse.
• stop_reason : La raison pour laquelle Claude s’est arrêté.
• stop_sequence : La séquence d’arrêt utilisée, si vous en avez défini une.
• usage : Le nombre de tokens consommés en entrée et en sortie.

Le champ content surprend souvent au début. Ce n’est pas directement du texte. C’est généralement une liste de blocs, souvent un TextBlock. C’est pour ça qu’on récupère le texte avec response.content[0].text. J’ai vu pas mal de devs perdre dix minutes là-dessus, alors que le comportement est normal.

En pratique, les deux champs que je surveille vraiment sont stop_reason et usage. Si stop_reason vaut end_turn, Claude a terminé normalement. Si ça vaut max_tokens, la sortie a été coupée parce que la limite de tokens de réponse était trop basse. Et là, il faut souvent augmenter max_tokens ou demander une réponse plus courte.

usage, lui, sert à suivre les tokens d’entrée et de sortie. Donc les coûts, la taille de vos prompts, et les risques de dépasser la fenêtre de contexte. Sur des automatisations en production, c’est un champ que je loggue presque toujours.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-3-5-haiku-latest",
    max_tokens=300,
    messages=[
        {"role": "user", "content": "Résume ce texte en 3 phrases."}
    ]
)

print(response.content[0].text)
print("Stop reason :", response.stop_reason)
print("Input tokens :", response.usage.input_tokens)
print("Output tokens :", response.usage.output_tokens)

Champ	À quoi ça sert	Ce que je vérifie
id	Identifier la réponse.	Utile pour les logs et le debug.
type	Indiquer le type d’objet retourné.	Que c’est bien un message.
role	Savoir qui parle.	Souvent assistant.
content	Contenir les blocs de réponse.	Le texte dans content[0].text.
model	Afficher le modèle utilisé.	Que le bon modèle répond.
stop_reason	Expliquer pourquoi Claude s’arrête.	end_turn ou max_tokens.
stop_sequence	Afficher une séquence d’arrêt éventuelle.	Qu’elle n’a pas coupé trop tôt.
usage	Suivre les tokens consommés.	Coût, taille du prompt, contexte.

À quoi sert le prompt système ?

Le prompt système sert à poser le cadre durable de Claude. Je m’en sers pour définir son rôle, ses contraintes, son ton, ses règles de réponse et ses limites. En clair, c’est là que je dis à Claude “Tu travailles comme ça”, avant même de lui donner une tâche précise.

Dans l’API Claude, ce prompt se met dans le paramètre top-level system, séparé de la liste messages. Ce n’est pas un message user déguisé. C’est une consigne de fond qui reste active sur les tours de conversation, tant que vous la gardez dans vos appels API. Point important : l’API ne “se souvient” pas toute seule de vos anciens appels, donc si vous reconstruisez une conversation, vous devez aussi renvoyer le même system.

system	Cadre général : rôle, format attendu, ton, règles métier, limites.
messages	Conversation réelle : demandes utilisateur et réponses assistant précédentes.

from anthropic import Anthropic

client = Anthropic(api_key="VOTRE_CLE_API")

response = client.messages.create(
    model="claude-3-5-sonnet-latest",
    max_tokens=500,

    # Ici, on place le prompt système.
    system=(
        "Tu es un relecteur de code Python. "
        "Réponds uniquement avec le code corrigé. "
        "N'explique pas les changements, sauf si je te le demande explicitement."
    ),

    # Ici, on place les messages de conversation.
    messages=[
        {
            "role": "user",
            "content": """Corrige ce code Python :

def moyenne(nombres):
    total = 0
    for n in nombres
        total += n
    return total / len(nombres)

print(moyenne([10, 12, 14]))
"""
        }
    ],
)

print(response.content[0].text)

Mon observation honnête : un bon prompt système évite beaucoup de post-traitement. Quand j’attends un format précis, une posture précise ou des règles métier, je préfère les écrire là plutôt que de les répéter dans chaque message utilisateur. J’ai vu ça chez un client qui voulait toujours des réponses en JSON strict. Au début, ils le rappelaient dans chaque demande. Ça marchait “à peu près”. Une fois la règle mise dans system, les sorties sont devenues beaucoup plus propres.

Comment streamer les réponses ?

Le streaming permet de recevoir la réponse au fil de sa génération, au lieu d’attendre que tout soit terminé. C’est exactement ce qu’on veut quand on construit une interface qui doit “vivre” pendant que Claude répond.

Je l’utilise surtout dans les cas où l’attente se voit côté utilisateur. Une interface chat, une génération longue, un assistant interne, un outil qui produit des logs en temps réel… Là, afficher les morceaux dès qu’ils arrivent change tout. Le modèle ne va pas forcément plus vite. Mais l’utilisateur a une sensation de fluidité, et ça rend l’attente beaucoup plus acceptable.

Avec le SDK Python officiel Anthropic, l’usage reste très proche d’un appel classique. La différence, c’est qu’on passe par client.messages.stream, puis on lit les fragments de texte au fur et à mesure.

from anthropic import Anthropic

client = Anthropic()

with client.messages.stream(
    model="claude-3-5-sonnet-20241022",
    max_tokens=800,
    messages=[
        {
            "role": "user",
            "content": "Explique-moi simplement ce qu'est une API."
        }
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final_message = stream.get_final_message()

print("\nStop reason:", final_message.stop_reason)
print("Usage:", final_message.usage)

Le point important, c’est que la boucle affiche chaque morceau dès qu’il est disponible. Pour un prototype, c’est souvent suffisant. J’ai déjà vu des équipes brancher ça en une heure dans une app interne, et l’effet côté utilisateur était immédiat.

Pour une vraie application, je fais quand même attention à quelques sujets. Le streaming ajoute un peu de complexité, surtout si l’utilisateur ferme l’onglet, annule la demande ou si le réseau coupe au milieu.

• Je gère les erreurs réseau, même si le SDK Anthropic prévoit déjà des retries, c’est-à-dire des tentatives automatiques en cas d’échec temporaire.
• Je définis des timeouts pour éviter qu’une requête reste bloquée trop longtemps.
• Je journalise stop_reason et usage quand ils sont disponibles, surtout pour suivre les coûts et comprendre pourquoi une réponse s’est arrêtée.
• Je sépare la logique métier de l’affichage du flux. Sinon, le code devient vite pénible à maintenir.

Mode	Usage recommandé	Avantage	Point d’attention
Appel classique	Réponses courtes, traitements backend, scripts simples.	Plus simple à coder et à tester.	L’utilisateur attend sans retour visuel.
Streaming	Chat, génération longue, assistant interne, logs en temps réel.	Expérience beaucoup plus fluide.	Il faut gérer annulation, timeout, logs et coût.

Alors, on le branche où dans votre application ?

Démarrer avec l’API Claude en Python, ce n’est pas compliqué. Le point important, c’est de partir propre : SDK officiel, clé API hors du code, appel Messages bien structuré, lecture sérieuse de l’objet réponse. Après ça, les prompts système donnent un vrai cadre à Claude, et le streaming améliore nettement l’expérience dès qu’on génère des réponses longues. Je vois souvent des projets IA bloquer non pas sur le modèle, mais sur ces détails d’intégration. Une fois qu’ils sont maîtrisés, vous pouvez brancher Claude dans un outil interne, un assistant, un workflow métier ou une app Python avec beaucoup moins de friction.

FAQ

• Quelle version de Python faut-il pour utiliser l’API Claude ?
  Il faut Python 3.9 ou plus. C’est la base recommandée pour utiliser le SDK Python officiel d’Anthropic sans perdre du temps sur des incompatibilités inutiles.
• Où faut-il stocker la clé API Claude ?
  Je la stocke dans une variable d’environnement appelée ANTHROPIC_API_KEY. Le SDK sait la lire automatiquement. Évitez de la mettre en dur dans le code, surtout si le projet passe ensuite sur Git ou en production.
• À quoi sert max_tokens dans un appel Claude ?
  max_tokens fixe le plafond de tokens générés en sortie. Si la valeur est trop basse, Claude peut couper sa réponse. C’est donc un paramètre à surveiller, surtout pour les réponses longues ou structurées.
• Comment récupérer le texte renvoyé par Claude en Python ?
  Dans le cas courant, le texte se récupère avec response.content[0].text. La réponse n’est pas juste une chaîne brute, c’est un objet Message avec plusieurs champs utiles comme stop_reason, usage et model.
• Quand utiliser le streaming avec l’API Claude ?
  Le streaming est utile quand l’utilisateur ne doit pas attendre toute la réponse d’un coup. Pour un chat, un assistant interne ou une génération longue, c’est souvent beaucoup plus agréable. On affiche les morceaux de réponse au fur et à mesure.

 

 

A propos de l’auteur

Je suis Franck Scandolera, expert et formateur en Tracking avancé server-side, Analytics Engineering, automatisation No/Low Code avec n8n, intégration de l’IA en entreprise et SEO/GEO. J’accompagne des équipes qui veulent connecter leurs données, leurs outils et leurs modèles IA sans monter des usines à gaz. J’ai travaillé pour des clients comme Logis Hôtel, Yelloh Village, BazarChic, la Fédération Française de Football ou Texdecor. Je dirige l’agence webAnalyste et l’organisme Formations Analytics. Si vous voulez intégrer Claude, automatiser vos process ou fiabiliser vos pipelines data, contactez-moi.