Comment utiliser l’API Claude en Python ?

L’API Claude en Python se lance vite avec le SDK anthropic, une clé API et un premier client.messages.create(). Le vrai sujet, c’est de faire propre dès le départ : clé en variable d’environnement, réponse typée, tokens suivis, system prompt clair et streaming quand l’usage le justifie.

De quoi avez-vous besoin ?

Il faut Python 3.9+, un compte Claude Console, une clé API et le SDK officiel anthropic installé avec pip. Avec ça, vous pouvez appeler Claude proprement depuis Python, sans partir dans du bricolage HTTP dès le départ.

Le SDK anthropic simplifie les appels à l’API Messages de Claude. L’API Messages, c’est l’interface principale pour envoyer une conversation au modèle et récupérer sa réponse. Le SDK fournit des objets typés, donc plus lisibles et moins fragiles, et il gère une partie de la plomberie comme les retries, c’est-à-dire les nouvelles tentatives automatiques quand une requête échoue temporairement.

Pour l’installation, je pars généralement sur ça :

• pip install anthropic
• pip install python-dotenv si vous voulez charger une clé depuis un fichier .env en local.

Le point à ne pas rater, c’est la clé API. Je ne la colle jamais directement dans un script. Pas dans un notebook. Pas dans un fichier Python. Pas dans un repo Git. La bonne pratique, c’est d’utiliser la variable d’environnement ANTHROPIC_API_KEY. En local, un fichier .env avec python-dotenv fait très bien le job, tant que ce fichier reste ignoré par Git.

Pourquoi c’est important ? Parce qu’en production, une clé doit pouvoir être remplacée vite. C’est ce qu’on appelle la rotation de clé. Ça évite aussi de casser vos déploiements sur serveur, dans une chaîne CI/CD, ou dans un outil d’automatisation type Make, n8n ou Airflow. J’ai déjà vu des projets IA bloqués non pas à cause du modèle, mais à cause d’une clé collée dans un notebook puis poussée dans un repo. C’est bête, mais ça arrive souvent.

Besoin	Rôle	Bonne pratique
Python 3.9+	Exécuter le code client	Utiliser une version récente et maintenue
Compte Claude Console	Créer et gérer l’accès API	Centraliser les clés et surveiller l’usage
Clé API	Authentifier les requêtes	La stocker dans ANTHROPIC_API_KEY ou un .env local
SDK anthropic	Simplifier les appels à Claude	L’installer avec pip et éviter les requêtes HTTP maison au début

Comment faire le premier appel ?

Le premier appel se fait avec anthropic.Anthropic(), puis client.messages.create(), en indiquant le modèle, max_tokens et la liste messages. C’est vraiment le minimum pour envoyer une question à Claude et récupérer une réponse exploitable.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model='claude-3-5-sonnet-20240620',
    max_tokens=200,
    messages=[
        {
            'role': 'user',
            'content': 'Explique-moi les variables Python en une phrase.'
        }
    ]
)

print(response.content[0].text)

model choisit le modèle Claude à utiliser. Ici, j’utilise claude-3-5-sonnet-20240620, qui est un bon choix généraliste pour tester vite, écrire, raisonner, résumer ou générer du code.

max_tokens fixe un plafond de sortie. Ce n’est pas une promesse de longueur exacte. Si je mets 200, je dis juste à Claude : “Ne dépasse pas environ 200 tokens en réponse”. Un token, pour simplifier, c’est un petit morceau de texte. Parfois un mot, parfois une partie de mot.

messages contient l’historique de conversation. Chaque élément représente un tour d’échange avec un role et un content. Dans ce cas simple, le premier tour doit être un message user, parce que c’est vous qui posez la demande initiale.

Ce format est très pratique parce qu’il prépare déjà la suite. Si vous voulez construire une vraie conversation multi-tours, vous réinjectez simplement les échanges précédents dans messages. Claude reçoit alors le contexte complet, pas juste la dernière question.

Pour un POC, cet exemple suffit largement. Je l’ai fait des dizaines de fois avec des clients pour valider une idée en 15 minutes. Mais pour une app business, je sépare vite la configuration, le prompt, l’appel API et le traitement de la réponse. Ça évite le script spaghetti au bout de deux jours, et croyez-moi, ça arrive vite.

L’étape suivante, c’est de comprendre l’objet retourné par l’API. C’est là qu’on détecte les coupures, les tokens consommés et surtout le vrai texte utile à exploiter.

Que contient la réponse ?

La réponse de l’API Claude n’est pas juste une chaîne de texte. Le SDK anthropic renvoie un objet Message typé, avec plusieurs champs exploitables dans votre code. C’est important, parce qu’en production, on ne veut pas seulement afficher une phrase. On veut comprendre ce qui s’est passé.

Dans cet objet, on retrouve des champs comme id, type, role, content, model, stop_reason et usage. Le champ content est une liste de blocs. Très souvent, ce sont des TextBlock, c’est-à-dire des blocs contenant du texte généré par Claude.

Dans le cas le plus simple, l’extraction idiomatique du texte ressemble à ça :

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

Ce petit détail évite pas mal de confusion. J’ai déjà vu des intégrations où quelqu’un essayait de traiter toute la réponse comme une string, puis s’étonnait que ça casse dès qu’il voulait logger les coûts ou analyser la raison d’arrêt. En vrai, l’objet complet est beaucoup plus utile que le texte seul.

stop_reason indique pourquoi Claude s’est arrêté. Ça peut être une fin naturelle, ou une limite atteinte à cause de max_tokens. Et ça fait directement le lien avec le chapitre précédent : si max_tokens est trop bas, la réponse peut être coupée. Ce n’est pas forcément un bug du modèle. C’est souvent juste un plafond trop serré.

usage donne les tokens d’entrée et de sortie. Un token, pour simplifier, c’est un morceau de texte utilisé par le modèle pour lire ou générer une réponse. Ce champ sert à suivre les coûts, repérer les prompts trop longs, ajuster les limites et dimensionner proprement une app.

Dans un workflow n8n, une app Python ou un backend, je ne logge presque jamais seulement le texte final. Je garde aussi stop_reason et usage. C’est souvent là qu’on comprend les comportements bizarres avant d’accuser l’IA.

Champ	Signification	Utilité en production
id	Identifiant unique du message	Retrouver et tracer une réponse précise
type	Type d’objet renvoyé par l’API	Vérifier qu’on manipule bien un message
role	Rôle associé à la réponse, souvent assistant	Distinguer les messages utilisateur et assistant
content	Liste de blocs, souvent des TextBlock	Extraire le texte avec response.content[0].text
model	Modèle Claude utilisé	Comparer les performances et les coûts par modèle
stop_reason	Raison pour laquelle Claude s’est arrêté	Détecter une réponse coupée ou une fin normale
usage	Tokens consommés en entrée et en sortie	Suivre les coûts et ajuster les limites

À quoi sert le system prompt ?

Le system prompt sert à définir le rôle, les contraintes et le comportement durable de Claude sur tout le fil de conversation. Dans l’API Messages, system est un paramètre séparé de messages. Ce n’est pas un message utilisateur caché. C’est une instruction de cadrage persistante, posée au-dessus de l’échange.

Concrètement, si j’utilise Claude pour relire du Python, je peux lui donner un rôle très net dès le départ :

from anthropic import Anthropic

client = Anthropic()

system_prompt = "Tu es un relecteur de code Python. Réponds uniquement avec du code corrigé, sans explication."

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=500,
    system=system_prompt,
    messages=[
        {
            "role": "user",
            "content": "Corrige ce code Python :\n\nprint('hello'\n"
        }
    ]
)

print(response.content[0].text)

Ça évite de répéter dans chaque message utilisateur : “Tu es un relecteur Python, ne donne pas d’explication, réponds seulement avec le code”. C’est plus propre. Il y a moins de bruit dans les prompts, le comportement reste plus cohérent, et le code devient plus maintenable. Quand je reprends un projet client six mois plus tard, je préfère largement modifier une variable system_prompt claire plutôt que fouiller dix prompts utilisateurs bricolés à la main.

Mais je nuance un point. Un system prompt ne remplace pas une validation côté application. Si votre app attend du JSON, il faut parser le JSON et gérer les erreurs. Si elle attend du code, il faut éventuellement lancer des tests. Si elle attend une réponse courte, il faut contrôler la longueur. Le modèle suit les consignes, mais votre application doit rester responsable de ce qu’elle accepte.

Pour un client, je préfère souvent écrire un system prompt court, très explicite, puis le tester sur des cas réels. Une charte de 80 lignes que personne ne maintient, ça finit souvent par créer plus de confusion que de contrôle.

Mes bonnes pratiques sont simples :

• Définir un rôle clair pour Claude.
• Ajouter des contraintes vérifiables, pas des intentions floues.
• Indiquer le format de sortie attendu.
• Éviter les consignes contradictoires.
• Ajouter un exemple si le format est sensible ou ambigu.

Quand utiliser le streaming ?

Le streaming devient utile quand l’utilisateur doit voir la réponse arriver progressivement, ou quand la génération peut prendre plusieurs secondes. C’est surtout une question d’expérience utilisateur. Si quelqu’un attend devant une interface, voir les premiers mots arriver change tout. Même si le temps total est identique, la perception est meilleure.

Dans une interface conversationnelle, un assistant interne ou un outil de rédaction, je l’active assez vite dès que les réponses deviennent longues. Un client m’avait demandé un assistant pour générer des synthèses de dossiers. Sans streaming, les utilisateurs pensaient que l’outil était bloqué au bout de 6 ou 7 secondes. Avec le streaming, ils voyaient la réponse se construire, donc ils attendaient sans stress.

Le principe est simple. Au lieu d’attendre l’objet final renvoyé par l’API Claude, votre application reçoit des morceaux d’événements pendant la génération. Elle peut ensuite afficher le texte au fil de l’eau, ou le reconstruire en mémoire pour produire une réponse complète à la fin.

Ça ne veut pas dire qu’on oublie le reste. Même en streaming, il faut garder une logique propre sur les tokens, les erreurs, les timeouts et le format final attendu. Un token, c’est grosso modo un morceau de texte que le modèle lit ou génère. Un timeout, c’est le délai maximum avant de considérer que l’appel a échoué. Et le format final, c’est ce que votre code attend vraiment à la fin, par exemple du texte simple, du JSON, ou une structure typée.

Mon approche est assez pragmatique. Je commence souvent sans streaming pour valider le prompt, la réponse typée, les contrôles et les cas d’erreur. C’est beaucoup plus simple à debugger. Une fois que la logique est stable, je passe en streaming si l’UX le demande vraiment.

Cas d’usage	Streaming recommandé	Raison
Chatbot ou assistant conversationnel	Oui	L’utilisateur voit la réponse arriver et l’interface paraît plus rapide.
Outil de rédaction ou génération longue	Oui	Le texte peut prendre plusieurs secondes, donc l’affichage progressif améliore le confort.
Assistant interne pour analyse de documents	Souvent oui	Les réponses sont parfois longues et l’utilisateur attend devant l’écran.
Traitement batch	Non	Personne ne regarde la réponse arriver, donc une réponse complète est plus simple.
Automatisation backend silencieuse	Non	Le code a surtout besoin d’un résultat final fiable et facile à contrôler.

Et maintenant, vous le branchez où dans votre app ?

Pour utiliser Claude en Python proprement, je pars simple : SDK anthropic, clé API hors du code, premier appel avec client.messages.create(), puis lecture de response.content[0].text. Après ça, je regarde vite stop_reason et usage, parce que c’est là qu’on comprend les coupures et la consommation de tokens. Le system prompt sert à cadrer le rôle de Claude sans polluer chaque message. Le streaming, lui, arrive quand l’expérience utilisateur en a besoin. Si vous posez ces bases dès le début, vous gagnez du temps, vous debuggez mieux et vous construisez une intégration IA plus fiable pour votre business.

FAQ

• Quelle version de Python faut-il pour utiliser l’API Claude ?
  Je recommande Python 3.9 ou plus récent, avec le SDK officiel anthropic installé via pip. Ça évite pas mal de soucis de compatibilité et ça colle à une base propre pour un projet actuel.
• Où mettre la clé API Claude en Python ?
  Je ne la mets jamais directement dans le code. Le plus propre, c’est d’utiliser la variable d’environnement ANTHROPIC_API_KEY. En local, un fichier .env chargé avec python-dotenv peut faire le job, à condition de ne pas le pousser dans Git.
• Comment récupérer le texte généré par Claude ?
  Avec le SDK Python, la réponse est un objet typé. Dans le cas courant, le texte se récupère avec response.content[0].text. C’est plus fiable que de traiter la réponse comme une simple chaîne brute.
• À quoi sert max_tokens dans un appel API Claude ?
  max_tokens fixe une limite maximale pour la réponse générée. Ce n’est pas une longueur garantie. Si la valeur est trop basse, Claude peut s’arrêter avant d’avoir fini, et il faut regarder stop_reason pour le confirmer.
• Quelle différence entre system et messages ?
  system sert à cadrer le rôle et les règles globales de Claude sur toute la conversation. messages contient les échanges entre l’utilisateur et l’assistant. Je mets les consignes persistantes dans system, et les demandes ponctuelles dans messages.

 

 

A propos de l’auteur

Je suis Franck Scandolera, responsable de l’agence webAnalyste et de l’organisme Formations Analytics. J’accompagne des équipes sur le tracking avancé server-side, l’Analytics Engineering, l’automatisation No/Low Code avec n8n, l’intégration de l’IA en entreprise et le SEO/GEO. J’ai travaillé avec des clients comme Logis Hôtel, Yelloh Village, BazarChic, la Fédération Française de Football ou Texdecor. Si vous voulez intégrer Claude, automatiser vos workflows IA ou structurer vos données proprement, contactez-moi, je peux vous aider à passer du test sympa au vrai usage business.