Comment utiliser l’API Claude en Python ?

On utilise l’API Claude en Python avec le SDK anthropic, une clé API sécurisée et un appel à client.messages.create(). Le vrai sujet, c’est moins le premier appel que la bonne structure des messages, la lecture de la réponse et les system prompts. C’est là que ça devient propre.

De quoi avez-vous besoin avant de coder ?

Pour démarrer avec l’API Claude en Python, il vous faut quatre choses simples : Python 3.9 ou plus, un compte Anthropic, une clé API, et le package Python officiel anthropic.

Python 3.9 minimum, c’est la base pour éviter les surprises avec les dépendances modernes. Vous pouvez vérifier votre version avec python –version. Si vous êtes sur une vieille version, je vous conseille de mettre à jour avant même de tester, sinon vous risquez de perdre du temps sur des erreurs qui n’ont rien à voir avec Claude.

Ensuite, il vous faut un compte Anthropic. C’est là que vous récupérez votre clé API. Une API, c’est simplement une interface qui permet à votre code de parler à Claude. La clé API sert à vous identifier, un peu comme un mot de passe technique.

Le package à installer s’appelle anthropic. Vous l’installez avec pip install anthropic. C’est le SDK officiel, SDK voulant dire kit de développement logiciel. En pratique, il simplifie les appels à l’API Messages de Claude, donc l’API utilisée pour envoyer un message et recevoir une réponse. Vous n’avez pas à gérer vous-même toute la plomberie HTTP, les headers, les formats de requête, les erreurs basiques. Et franchement, pour tester vite mais proprement, c’est ce qu’on veut.

Le point à ne pas rater, c’est la clé API. Je la stocke dans une variable d’environnement nommée ANTHROPIC_API_KEY. Sur macOS ou Linux, ça ressemble à export ANTHROPIC_API_KEY=sk-ant-…. Sur Windows, vous pouvez passer par les variables d’environnement système ou votre terminal selon votre setup.

Dans un projet local, vous pouvez aussi utiliser un fichier .env. Ce fichier contient vos variables sensibles, par exemple ANTHROPIC_API_KEY=sk-ant-…. Mais il ne doit jamais partir dans Git. Ajoutez-le à votre .gitignore. J’ai déjà vu des clés API copiées dans des notebooks ou des dépôts Git, et c’est exactement le genre de détail qui finit mal. Une clé exposée peut être utilisée par n’importe qui, et la facture peut monter vite.

Prérequis	Rôle	Point d’attention
Python 3.9+	Faire tourner le SDK et votre script Python.	Vérifier avec python –version avant de commencer.
Compte Anthropic	Créer un accès à l’API Claude.	Activer la facturation si nécessaire selon votre usage.
Clé API	Authentifier vos appels vers Claude.	Ne jamais la mettre en dur dans le code.
Package anthropic	Utiliser le SDK officiel Python.	Installer avec pip install anthropic.

Comment faire le premier appel API ?

Le premier appel API se fait simplement avec Anthropic(), puis avec client.messages.create(). Si votre variable ANTHROPIC_API_KEY est bien configurée comme dans le chapitre précédent, le client la récupère automatiquement. Vous n’avez pas besoin de coller votre clé dans le code, et franchement, c’est mieux comme ça.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=300,
    messages=[
        {
            "role": "user",
            "content": "Explique simplement ce qu'est une liste en Python."
        }
    ]
)

texte = response.content[0].text

print(texte)

Dans cet exemple, il y a trois paramètres à bien comprendre.

• model indique le modèle Claude que vous voulez utiliser. Ici, j’utilise Claude 3.5 Sonnet, un bon choix général pour démarrer.
• max_tokens limite la longueur de la réponse. Ce n’est pas un bouton magique pour améliorer la qualité, c’est juste une limite de sortie. Un token, grosso modo, c’est un morceau de mot.
• messages contient la conversation envoyée à Claude.

Le champ messages est une liste de dictionnaires Python. Chaque dictionnaire contient au minimum un role et un content. Le rôle user correspond à votre demande, celle que vous envoyez à Claude. Plus tard, vous verrez aussi des échanges avec des rôles assistant, mais pour un premier test, user suffit largement.

Champ	Rôle
role	Indique qui parle dans la conversation.
content	Contient le texte envoyé à Claude.

Pour récupérer la réponse, j’utilise response.content[0].text. C’est souvent le premier réflexe à avoir quand on débute avec l’API Claude en Python.

Mon conseil pour les premiers tests : commencez avec un max_tokens raisonnable, par exemple 200 ou 300. Ça évite les réponses interminables, ça rend les tests plus lisibles, et ça vous aide à mieux contrôler les coûts. J’ai vu pas mal de clients lancer leurs premiers essais avec des limites trop larges, puis se demander pourquoi tout part dans tous les sens. Autant garder la main dès le début.

Comment lire la réponse de Claude ?

La réponse de Claude se lit comme un objet Message, pas comme une simple chaîne de texte. C’est important, parce que cet objet contient beaucoup plus que la réponse affichée à l’utilisateur. On y trouve le contenu généré, le modèle utilisé, la raison pour laquelle Claude s’est arrêté, et les infos de consommation en tokens.

Dans un cas simple, le texte est souvent ici :

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

Mais je vous conseille de ne pas coder trop vite en supposant que tout sera toujours dans response.content[0].text. Le champ content est une liste de blocs. Aujourd’hui vous avez souvent un bloc texte, mais selon les usages, les outils, ou les formats de réponse, il peut y avoir plusieurs blocs avec des types différents.

Au début d’un projet, j’affiche souvent l’objet complet, ou je le loggue proprement en environnement de test. Franchement, ça évite de coder à l’aveugle. Chez un client, on avait une erreur bizarre sur une automatisation Make + Python. En regardant simplement l’objet complet, on a vu que la génération s’arrêtait à cause d’une limite de tokens, pas à cause d’un bug métier.

print(response)

# Ou plus ciblé
print(response.id)
print(response.model)
print(response.stop_reason)
print(response.usage)
print(response.content[0].text)

Le champ stop_reason est à surveiller de près. Il explique pourquoi Claude a arrêté sa génération. Ça peut être une fin naturelle, une limite de tokens atteinte, ou une autre condition liée à l’appel. Si vous obtenez une réponse coupée, commencez par regarder ici avant de toucher à tout le reste.

Le champ usage est aussi clé. Il indique les tokens d’entrée et de sortie. Un token, pour simplifier, c’est un morceau de texte utilisé pour calculer le coût et la taille du contexte. Si vous voulez maîtriser votre budget, optimiser vos prompts, ou repérer une dérive, c’est ce champ qu’il faut suivre.

Champ	Utilité concrète
id	Identifiant unique de la réponse, pratique pour tracer un appel ou débugger.
type	Type d’objet renvoyé, généralement un message.
role	Rôle de l’émetteur, souvent assistant pour une réponse de Claude.
content	Liste de blocs contenant la réponse, souvent lisible avec response.content[0].text.
model	Modèle Claude utilisé pour générer la réponse.
stop_reason	Raison d’arrêt de la génération, utile pour comprendre une réponse coupée ou terminée.
usage	Consommation en tokens d’entrée et de sortie, indispensable pour suivre les coûts.

À quoi servent les system prompts ?

Les system prompts servent à donner à Claude un rôle, un cadre ou des contraintes qui restent valables pendant toute la conversation. C’est un peu la fiche de poste du modèle. Je lui dis comment il doit se comporter, avant même que l’utilisateur pose sa vraie demande.

Dans l’API Claude, le system prompt ne se met pas dans le champ messages. Il est fourni à part, avec le paramètre system. Et point important, il ne remplace pas la demande utilisateur. Le system définit le comportement attendu. Le user pose la demande concrète.

Voici un exemple simple en Python. Je configure Claude comme relecteur de code Python, avec une contrainte assez stricte : il doit répondre uniquement avec le code corrigé, sans explication.

from anthropic import Anthropic

client = Anthropic(api_key="votre_cle_api")

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1000,
    system="Tu es un relecteur expert en Python. Corrige le code fourni. Réponds uniquement avec le code corrigé, sans explication.",
    messages=[
        {
            "role": "user",
            "content": "Corrige ce code :\n\ndef add(a,b)\n    return a + b"
        }
    ]
)

print(response.content[0].text)

On reste sur le même appel que dans les chapitres précédents, client.messages.create(). La seule différence, c’est qu’on ajoute le paramètre system. C’est pratique parce qu’on garde une séparation propre entre le cadre global et la demande du moment.

Les contraintes utiles que je mets souvent dans un system prompt ressemblent à ça :

• Répondre en français.
• Rester concis et aller droit au but.
• Ne pas inventer d’information si la donnée manque.
• Respecter un format JSON précis.
• Refuser de sortir du rôle demandé.
• Produire uniquement du code, sans commentaire autour.

Un exemple classique en automatisation, c’est Claude qui doit renvoyer un JSON propre pour être lu ensuite par Make, n8n ou un script Python. Là, le system prompt est très utile, parce qu’il réduit les réponses “créatives” qui cassent le traitement derrière.

Attention quand même. Un system prompt trop long, flou ou contradictoire rend les résultats moins prévisibles. J’ai déjà vu des prompts qui demandaient à Claude d’être “très détaillé” puis “ultra concis” deux lignes plus bas. Dans ce cas, il fait de son mieux, mais vous perdez en stabilité. Je préfère un cadre court, clair, et une demande utilisateur précise.

Comment structurer un usage propre en projet ?

Un usage propre, pour moi, c’est simple : je sépare la configuration, l’appel API, le prompt et le traitement de la réponse. Pas besoin de monter une architecture énorme. Juste éviter le gros fichier où la clé API, le texte du prompt, l’appel à Claude et les prints sont mélangés partout.

Dans un petit script Python, je fais souvent quelque chose comme ça :

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
)

SYSTEM_PROMPT = "Tu es un assistant clair, concis et fiable."

def envoyer_message(message_utilisateur):
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=500,
        system=SYSTEM_PROMPT,
        messages=[
            {
                "role": "user",
                "content": message_utilisateur
            }
        ]
    )

    texte = response.content[0].text

    print("Usage :", response.usage)
    print("Stop reason :", response.stop_reason)

    return texte

resultat = envoyer_message("Résume ce texte en 5 lignes.")
print(resultat)

Le point important ici, ce n’est pas juste que le script marche. C’est que chaque partie a son rôle. La clé API reste dans une variable d’environnement. Le system prompt est visible et modifiable. La fonction fait l’appel à Claude. La réponse est récupérée proprement avec response.content[0].text. Et en test, j’affiche aussi usage et stop_reason, parce que ça permet de comprendre ce qui s’est passé.

En entreprise, franchement, le problème n’est presque jamais de faire marcher le premier appel. Ça, on y arrive vite. Le vrai sujet, c’est de garder un code lisible, sécurisé et contrôlable trois semaines plus tard, quand quelqu’un veut changer le prompt, limiter les coûts ou brancher ça dans un workflow existant.

Cette séparation aide aussi à faire évoluer le script. Aujourd’hui, c’est un test local. Demain, ça peut devenir un petit outil interne, une automatisation low code, ou une étape dans un workflow avec Make, n8n, Airtable, Notion ou un CRM.

Les bonnes pratiques que je garde presque toujours :

• Clé API en variable d’environnement, jamais écrite en dur dans le code.
• max_tokens contrôlé, pour éviter les réponses trop longues et les coûts inutiles.
• Messages structurés, avec un rôle user clair et un contenu propre.
• Réponse inspectée, avec le texte, l’usage et la raison d’arrêt.
• System prompt clair, pour cadrer le comportement de Claude.

Test rapide	Usage projet
Tout dans un seul script	Configuration, prompt et appel séparés
Clé API écrite en dur	Clé API en variable d’environnement
On regarde seulement le texte	On inspecte aussi usage et stop_reason
Prompt bricolé dans l’appel	System prompt clair et maintenable

Vous lancez votre premier appel Claude proprement ?

Utiliser l’API Claude en Python, ce n’est pas compliqué. J’installe le SDK anthropic, je sécurise la clé API, puis j’appelle client.messages.create() avec un modèle, un max_tokens et une liste de messages claire. Là où ça devient sérieux, c’est dans la lecture de l’objet de réponse, surtout content, stop_reason et usage. Les system prompts ajoutent ensuite le cadre nécessaire pour obtenir des réponses plus stables. Si vous gardez cette base simple, vous pouvez tester vite sans bricoler. Le bénéfice pour vous, c’est un premier socle fiable pour intégrer Claude dans vos scripts, vos outils internes ou vos automatisations business.

FAQ

• Quelle version de Python faut-il pour utiliser l’API Claude ?
  Il faut Python 3.9 ou une version plus récente. C’est la base recommandée pour utiliser correctement le SDK anthropic et éviter les problèmes de compatibilité inutiles.
• Comment installer le SDK Python de Claude ?
  J’installe le package avec pip install anthropic. Ensuite, je configure ma clé API dans la variable d’environnement ANTHROPIC_API_KEY pour que le client Python puisse l’utiliser sans l’écrire directement dans le script.
• Pourquoi ne faut-il pas mettre la clé API dans le code ?
  Parce qu’une clé copiée dans un script, un notebook ou un dépôt Git peut fuiter très vite. Le bon réflexe, c’est de la stocker dans une variable d’environnement ou dans un fichier .env local non partagé.
• À quoi sert max_tokens dans un appel à l’API Claude ?
  max_tokens fixe la longueur maximale de la réponse générée. Ce n’est pas un bouton magique pour améliorer la qualité, c’est surtout une limite de sortie utile pour contrôler la taille des réponses et les coûts.
• Quelle est la différence entre messages et system prompt ?
  messages contient la conversation, notamment les demandes envoyées avec le rôle user. Le system prompt sert à cadrer le comportement de Claude sur toute la conversation, par exemple définir un rôle, un ton ou des contraintes de format.

 

 

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 passer de tests IA isolés à des usages propres, fiables et exploitables dans leurs process. J’ai travaillé avec des références 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 workflows ou cadrer vos usages IA, contactez-moi.