Claude API en Python : le guide ultime pour débuter en 10 minutes

Pour commencer à utiliser l'API Claude de Anthropic, il faut trois choses : Python 3.9 ou plus récent, un compte gratuit sur la Claude Console et une clé API. Cette dernière s'obtient dans les paramètres de la console, sous l'onglet API Keys. Une fois la clé récupérée, la règle d'or est de ne jamais l'écrire directement dans votre code. Stockez-la plutôt dans une variable d'environnement pour éviter tout risque de fuite.

INSTALLER LE SDK PYTHON ET CONFIGURER LA CLÉ API

Le SDK officiel pour Python s'installe en une ligne de commande. Il suffit d'exécuter la commande suivante dans votre terminal :

pip install anthropic

Ensuite, créez une variable d'environnement nommée ANTHROPICAPIKEY et collez-y votre clé API. Si vous préférez, vous pouvez aussi utiliser un fichier .env à la racine de votre projet avec la bibliothèque python-dotenv. Le SDK lira automatiquement cette variable sans que vous ayez à la passer manuellement dans votre code.

FAIRE VOTRE PREMIÈRE REQUÊTE À L'API CLAUDE

L'entrée principale de l'API est la méthode client.messages.create(). Pour votre premier test, demandons à Claude d'expliquer ce qu'est une fenêtre de contexte — un concept essentiel à comprendre avant d'utiliser l'API. Voici comment procéder :

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=256,
    messages=[
        {
            "role": "user",
            "content": "In one sentence, what is a context window?"
        }
    ]
)

print(response.content[0].text)

Trois paramètres sont indispensables : le modèle à utiliser, le nombre maximum de tokens à générer (max_tokens) et la liste des messages. Cette dernière doit toujours commencer par un message de l'utilisateur.

COMPRENDRE LA STRUCTURE DE LA RÉPONSE

La réponse de l'API est un objet Message structuré. Voici à quoi il ressemble pour notre première requête :

Message(
  id='msg_01XFDUDYJgAACzvnptvVoYEL',
  type='message',
  role='assistant',
  content=[TextBlock(text='A context window is.', type='text')],
  model='claude-sonnet-5',
  stopreason='endturn',
  stop_sequence=None,
  usage=Usage(inputtokens=19, outputtokens=42)
)

Plusieurs champs méritent votre attention. stop_reason indique pourquoi Claude a arrêté de générer du texte. La valeur end_turn signifie que le modèle a terminé sa réponse de lui-même. Si vous voyez max_tokens, cela signifie que la réponse a été coupée à cause de votre limite, et qu'il faudra peut-être l'augmenter ou reformuler votre demande.

Le champ usage comptabilise les tokens en entrée et en sortie. Ces chiffres servent à la facturation et permettent de détecter si votre requête approche de la limite de la fenêtre de contexte. Le contenu est toujours une liste : dans le cas d'une réponse texte standard, elle contient un seul élément de type TextBlock. Pour extraire le texte, utilisez donc response.content[0].text.

UTILISER UN PROMPT SYSTÈME POUR GUIDER CLAUDE

Le prompt système permet de donner à Claude un rôle permanent, des contraintes ou un contexte qui s'appliquent à toute la conversation. Contrairement aux messages classiques, il est passé en paramètre séparé system et non dans la liste des messages. Voici un exemple où Claude agit comme un relecteur de code Python :

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=512,
    system=(
        "You are a Python code reviewer. "
        "Respond only with corrected or improved Python code. "
        "Do not explain changes unless the user explicitly asks."
    ),
    messages=[
        {
            "role": "user",
            "content": (
                "def get_user(id):\n"
                "    db = connect()\n"
                "    return db.query('SELECT * FROM users WHERE id=' + id)"
            )
        }
    ]
)

print(response.content[0].text)

Le prompt système reste actif pendant toute la conversation. Vous n'avez pas besoin de le répéter à chaque message. Cela permet de définir des règles de formatage, des instructions de rôle ou des contraintes de domaine qui persistent automatiquement.

RÉCUPÉRER LES RÉSULTATS EN TEMPS RÉEL AVEC LE STREAMING

Pour les requêtes qui prennent quelques secondes à traiter, le streaming affiche le texte au fur et à mesure de sa Génération, plutôt que d'attendre la réponse complète. Le SDK propose cette fonctionnalité via client.messages.stream(), utilisée comme un gestionnaire de contexte.

Voici comment l'implémenter pour expliquer le fonctionnement d'une liste Python :

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": "Walk me through what happens when a Python list grows beyond its initial capacity."
        }
    ]
) as stream:
    for chunk in stream.text_stream:
        print(chunk, end="", flush=True)

print()  # newline after stream ends

L'itérateur text_stream fournit des fragments de texte en temps réel. Chaque morceau est une chaîne de caractères incomplète, pas une phrase entière. Pour un affichage fluide, utilisez end="" et flush=True dans la fonction print().

Le gestionnaire de contexte garantit que la connexion HTTP est fermée proprement à la fin du bloc, même en cas d'erreur. Si vous avez besoin de l'objet Message complet après le streaming — y compris les comptes de tokens — appelez stream.getfinalmessage() avant la fermeture du bloc.

COMMENT FONCTIONNE UNE LISTE PYTHON EN ARRIÈRE-PLAN

Pour mieux comprendre l'exemple précédent, voici comment Python gère l'ajout d'éléments dans une liste quand elle atteint sa capacité maximale :

Python lists are dynamic arrays. When you append an element and the list has no
room, Python allocates a new, larger block of memory — typically 1.125x the current
size — copies all existing elements into it, and releases the old block. This
operation is O(n) in the worst case, but because it happens infrequently relative to
the number of appends, the amortized cost per append stays O(1). You can pre-allocate
capacity with a list comprehension or by passing an iterable to the list constructor
if you know the final size upfront.

En résumé, une liste Python est un tableau dynamique. Quand elle est pleine et qu'on ajoute un élément, Python alloue un nouveau bloc de mémoire plus grand — généralement 1,125 fois la taille actuelle — copie tous les éléments existants, puis libère l'ancien bloc. Cette opération est en O(n) dans le pire cas, mais comme elle se produit rarement comparée au nombre d'ajouts, le coût moyen par ajout reste en O(1). Si vous connaissez la taille finale de la liste à l'avance, vous pouvez pré-allouer sa capacité avec une list comprehension ou en passant un itérable au constructeur de liste.

LES BASES POUR ALLER PLUS LOIN

Vous avez maintenant les éléments essentiels pour commencer : faire des requêtes, lire les réponses structurées, utiliser des prompts système et gérer le streaming. L'API est sans état, ce qui signifie que vous devez envoyer l'historique complet de la conversation avec chaque requête. La documentation officielle propose des exemples pour gérer les erreurs, optimiser l'usage des tokens et créer des conversations multi-tours.

D'autres fonctionnalités avancées sont disponibles, comme les sorties structurées ou l'utilisation d'outils. Ces options sont détaillées dans la documentation du SDK. L'API Claude ouvre la porte à des intégrations puissantes dans vos projets Python, que ce soit pour automatiser des tâches, générer du code ou analyser des données.