Comment démarrer avec l’API Claude Python ?

J’intègre l’API Claude Python avec le SDK Anthropic, une clé API proprement stockée, puis un premier appel via client.messages.create. Le vrai sujet, c’est moins le lancement que la maîtrise des réponses, des tokens, des system prompts et des bases propres pour éviter les bricolages fragiles.

De quoi ai-je besoin avant de coder ?

Il faut Python 3.9 ou plus, un compte Claude Console, une clé API et le SDK Anthropic installé. Je préfère poser ces bases proprement avant de tester l’API, parce que les erreurs les plus bêtes viennent souvent de là. Une clé copiée en dur dans un script. Un terminal qui ne lit pas la bonne variable. Un environnement Python pas activé. Rien de spectaculaire, mais ça fait perdre du temps.

Pour Python, je pars sur Python 3.9+. C’est le minimum confortable pour utiliser le SDK Anthropic sans bricoler. Le SDK, c’est simplement la librairie Python officielle qui permet de parler à l’API Claude sans écrire tous les appels HTTP à la main.

Côté compte, il faut accéder à la Claude Console. Une fois connecté, je vais dans Settings, puis API Keys, et je crée une nouvelle clé. Cette clé API est un secret. Je la traite comme un mot de passe applicatif. Je ne la colle pas dans un fichier Python, je ne l’envoie pas par Slack, et je ne la commit jamais dans Git. J’ai déjà vu ça chez un client, une clé posée dans un repo “temporaire”. Le temporaire a duré six mois.

Ensuite, j’installe le SDK Anthropic avec pip. La commande est simple : pip install anthropic.

Le point important, c’est que le SDK Anthropic sait lire automatiquement la variable d’environnement ANTHROPIC_API_KEY. Ça évite de mettre la clé dans le code. Sur macOS ou Linux, je peux la configurer comme ça : export ANTHROPIC_API_KEY=’YOUR-API-KEY-HERE’.

Sur un vrai projet, j’utilise souvent un fichier .env avec python-dotenv, surtout quand il y a plusieurs variables à gérer. Mais ce fichier reste local. Je l’ajoute au .gitignore, et je ne le commit pas. La clé doit rester en dehors du code source.

Prérequis	Python 3.9+, un accès Claude Console, une clé API et le SDK Anthropic installé.
Rôle	Permettre à votre script Python d’appeler Claude proprement, sans gérer l’authentification à la main.
Erreur fréquente	Mettre la clé API directement dans le script ou oublier de définir ANTHROPIC_API_KEY.

Comment faire le premier appel API ?

Le premier appel passe par client.messages.create, avec un modèle, une limite max_tokens et une liste messages qui commence par un rôle user. C’est le point d’entrée le plus simple pour obtenir une réponse de Claude dans une application Python.

Avant ça, je pars du principe que votre clé API Anthropic est déjà disponible dans votre environnement, via ANTHROPIC_API_KEY. Le SDK la récupère automatiquement avec anthropic.Anthropic().

Exemple complet :

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
model= »claude-sonnet-5″,
max_tokens=300,
messages=[
{
« role »: « user »,
« content »: « Explique-moi en une phrase ce qu’est une API. »
}
]
)

print(response.content[0].text)

Les trois paramètres importants sont simples à comprendre.

• model choisit le modèle Claude à utiliser. Ici, j’utilise claude-sonnet-5.
• max_tokens fixe un plafond strict de génération. Un token, pour simplifier, c’est un morceau de texte. Ce n’est pas exactement un mot, mais ça sert à mesurer la taille d’une réponse.
• messages contient les tours de conversation. Chaque message a un role, comme user, et un content, c’est-à-dire le texte envoyé à Claude.

Attention à max_tokens. Ce n’est pas une suggestion. Si Claude atteint cette limite, il peut s’arrêter même si la réponse semblait continuer. Sur un résumé court, 300 tokens suffisent souvent. Sur une analyse longue, c’est vite trop bas.

Sur des intégrations client, je commence presque toujours avec un appel ultra simple comme celui-là. Pas de contexte compliqué, pas de règles métier, pas d’interface. Juste une question, une réponse. Ça évite de confondre un problème de prompt avec un problème de configuration. Et franchement, ça fait gagner beaucoup de temps.

Que contient la réponse de Claude ?

La réponse de Claude est un objet Message typé, pas juste une chaîne de texte. C’est une bonne nouvelle. Ça veut dire que je peux récupérer le texte, surveiller les tokens, comprendre pourquoi la génération s’est arrêtée, et journaliser proprement chaque appel API. En prod, c’est exactement ce qui évite les surprises.

Les champs que je regarde le plus souvent sont simples à lire. Le champ id identifie la réponse. Le champ type indique le type d’objet, généralement message. Le champ role indique qui parle, souvent assistant. Le champ model confirme le modèle utilisé. Le champ content contient la réponse réelle, mais attention, ce n’est pas directement du texte.

content est une liste. Dans le cas le plus courant, elle contient un bloc de texte, un TextBlock. L’extraction idiomatique du texte ressemble donc à ça :

text = response.content[0].text

C’est un détail bête, mais je l’ai vu casser pas mal d’intégrations chez des clients. Quelqu’un suppose que la réponse est une string, il la stocke telle quelle, et derrière tout le traitement plante ou journalise un objet illisible.

Le champ stop_reason est important. Quand il vaut end_turn, Claude a simplement fini son tour. C’est le cas normal. Quand il indique une coupure liée à max_tokens, ça veut dire que la limite de génération a arrêté la réponse. Dans ce cas, je ne traite pas forcément le résultat comme une réponse complète. Si Claude rédige un JSON, un email ou une analyse longue, une coupure au milieu peut rendre la sortie inutilisable.

Le champ stop_sequence indique la séquence qui a provoqué l’arrêt, si vous en avez configuré une. Sinon, il est souvent vide ou nul.

Le champ usage contient input_tokens et output_tokens. Les tokens sont les morceaux de texte que le modèle lit et génère. Je les regarde pour suivre les coûts, mais aussi pour voir si je m’approche des limites de contexte. Si les entrées grossissent trop, les réponses peuvent devenir plus chères, plus lentes, ou plus difficiles à fiabiliser.

Champ	Ce qu’il indique	Pourquoi je le regarde
id	L’identifiant unique du message	Pour tracer et journaliser un appel précis
type	Le type d’objet retourné	Pour vérifier que je manipule bien un message
role	Le rôle de l’émetteur, souvent assistant	Pour garder une conversation propre
content	La liste des blocs de contenu, souvent un TextBlock	Pour extraire le texte avec response.content[0].text
model	Le modèle utilisé pour générer la réponse	Pour auditer les appels et comparer les comportements
stop_reason	La raison de l’arrêt de la génération	Pour détecter une réponse complète ou coupée
stop_sequence	La séquence d’arrêt déclenchée, si présente	Pour comprendre un arrêt personnalisé
usage	Les tokens en entrée et en sortie	Pour surveiller les coûts et le contexte

À quoi sert un system prompt ?

Un system prompt sert à définir le rôle, les contraintes et le contexte global que Claude doit garder pendant l’échange. Dans l’API Messages, il se passe au niveau supérieur avec le paramètre system, séparé de la liste messages.

C’est une séparation importante. Le system fixe le cadre persistant. Les messages, eux, contiennent la conversation réelle : les demandes de l’utilisateur et les réponses de l’assistant.

system	Définit le rôle, les règles permanentes, le ton, les limites, le format attendu.
messages	Contient les échanges : ce que l’utilisateur demande maintenant, et les réponses précédentes si vous gardez un historique.

Par exemple, si je veux utiliser Claude comme relecteur de code Python, je ne vais pas répéter à chaque demande “Sois strict, améliore le code, ne fais pas d’explication”. Je mets ça dans le system. Ensuite, dans messages, je mets juste le code à améliorer.

from anthropic import Anthropic

client = Anthropic(api_key="VOTRE_CLE_API")

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=800,
    system="Tu es un relecteur de code Python. Tu renvoies uniquement du code amélioré. Tu n'expliques rien sauf si on te le demande explicitement.",
    messages=[
        {
            "role": "user",
            "content": """
Améliore ce code :

def total(prices):
    s = 0
    for p in prices:
        s = s + p
    return s
"""
        }
    ],
)

print(response.content[0].text)

Ce détail paraît simple, mais il change beaucoup de choses en production. J’ai vu pas mal de prompts devenir ingérables parce qu’on mélangeait tout dans le même bloc : les règles permanentes, la demande du moment, les données métier, parfois même des exemples et des exceptions partout.

Je préfère séparer proprement. Le rôle et les règles dans system. La demande actuelle dans messages. Les données métier dans un bloc clair, souvent généré par le code. C’est beaucoup plus facile à maintenir, surtout quand l’appel API finit dans un workflow n8n, un back-office ou un outil interne utilisé par plusieurs personnes.

Que faut-il surveiller avant la production ?

Avant la production, je surveille surtout les choses simples qui cassent vite : la sécurité de la clé API, la limite max_tokens, le stop_reason, l’usage des tokens et la façon dont mon application extrait la réponse. C’est basique, mais c’est souvent là que les premiers bugs arrivent.

Le SDK Python d’Anthropic aide déjà pas mal. Il fournit des objets typés, une interface propre pour appeler l’API Messages, et une gestion des retries, c’est-à-dire des nouvelles tentatives automatiques quand une requête échoue temporairement. Ça évite de réécrire toute la plomberie à la main. Mais ça ne veut pas dire que je peux brancher ça en production les yeux fermés.

Le point que je vérifie toujours, c’est l’extraction du texte. Dans un exemple rapide, on voit souvent quelque chose comme response.content[0].text. Ça marche pour comprendre le principe. Dans un vrai code applicatif, je ne suppose pas que cette structure existe toujours sans vérifier. Je contrôle que content contient bien un élément, que cet élément porte bien du texte, et que mon application sait quoi faire si la réponse est vide ou différente.

Je regarde aussi stop_reason. Cette valeur indique pourquoi Claude s’est arrêté. Par exemple, la génération peut s’arrêter parce que la limite de tokens est atteinte. Si je ne lis pas cette info, je peux afficher une réponse coupée sans m’en rendre compte. J’ai déjà vu ça chez un client : tout semblait fonctionner, sauf que certaines réponses longues finissaient au milieu d’une phrase. Le bug n’était pas dans le prompt, il était dans la limite choisie.

Le streaming est une question naturelle quand on veut afficher la réponse progressivement, comme dans une interface de chat. Mais je ne commence pas par là. Je préfère d’abord maîtriser l’appel Messages classique, la structure de la réponse, max_tokens, usage et stop_reason. Une fois cette base stable, le streaming devient beaucoup moins risqué.

• Clé hors du code pour éviter de la publier par erreur.
• Variable d’environnement configurée avant le déploiement.
• max_tokens choisi consciemment, pas laissé au hasard.
• stop_reason lu pour détecter une réponse coupée.
• usage journalisé pour suivre les tokens consommés.
• System prompt séparé du message utilisateur.
• Extraction du texte testée sans supposer que response.content[0].text existe toujours.

On démarre par quoi maintenant ?

Je commencerais simple : une clé API bien stockée, le SDK Anthropic installé, un premier appel avec client.messages.create, puis une lecture propre de response.content[0].text. Après ça, je regarde les champs qui comptent vraiment : stop_reason pour savoir si Claude a terminé correctement, usage pour suivre les tokens, et system pour cadrer le comportement du modèle. C’est cette base qui évite les intégrations bancales. Une fois qu’elle est solide, vous pouvez brancher Claude dans une app Python, un outil interne ou un workflow d’automatisation avec beaucoup moins de surprises.

FAQ

• Comment installer le SDK Anthropic pour utiliser l’API Claude en Python ?
  J’installe le SDK avec pip install anthropic, puis je configure la clé API dans une variable d’environnement nommée ANTHROPIC_API_KEY. Le SDK sait la lire automatiquement, ce qui évite de mettre la clé directement dans le script Python.
• Où faut-il stocker la clé API Claude ?
  Je la stocke dans une variable d’environnement, ou dans un fichier .env si le projet utilise python-dotenv. Je ne la mets jamais en dur dans le code, et je ne committe pas le fichier qui contient la clé. C’est un secret applicatif, pas une simple option de configuration.
• Quel est le rôle de max_tokens dans un appel à Claude ?
  max_tokens fixe le plafond strict de tokens que Claude peut générer en sortie. Si cette limite est atteinte, la réponse peut être coupée. C’est pour ça que je surveille aussi stop_reason dans l’objet de réponse, surtout dès qu’on veut exploiter le résultat dans une application.
• Comment récupérer le texte renvoyé par Claude en Python ?
  L’extraction classique se fait avec response.content[0].text. La réponse complète reste un objet Message typé, avec d’autres champs utiles comme id, model, stop_reason et usage. Je préfère garder cette structure en tête plutôt que traiter la réponse comme une simple chaîne de texte.
• À quoi sert le system prompt avec l’API Claude ?
  Le system prompt sert à poser le cadre global : rôle, contraintes, comportement attendu, contexte permanent. Il se passe dans le paramètre system au niveau supérieur, séparé de messages. C’est très pratique pour garder des règles stables dans une conversation ou une intégration métier.

 

 

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 références 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 process ou fiabiliser vos données, contactez-moi, je peux vous aider à aller droit au concret.