Comment utiliser l’API Claude en Python ?

L’API Claude s’utilise en Python avec le SDK anthropic, une clé API et un appel à client.messages.create(). Le vrai sujet, c’est de bien structurer les messages, lire la réponse, gérer les tokens, les prompts système et préparer l’intégration proprement.

De quoi ai-je besoin pour démarrer ?

Pour démarrer avec l’API Claude en Python, il faut Python 3.9 ou plus, un compte sur la console Claude, une clé API et le SDK Python anthropic.

Je commence toujours par sécuriser la clé API. C’est le genre de détail qui a l’air anodin, puis un jour quelqu’un la laisse dans un repo Git, ou dans un script partagé, et ça finit en incident. Une clé API, c’est comme un mot de passe. Je ne la mets jamais en dur dans le code.

Pour installer le SDK officiel, je lance simplement :

pip install anthropic

Ensuite, je gère la clé proprement. La méthode la plus simple, c’est la variable d’environnement ANTHROPIC_API_KEY. Le client Python d’Anthropic sait la lire directement depuis l’environnement, donc pas besoin de faire un truc du genre api_key= »sk-… » dans votre script. Ça évite les mauvaises surprises.

Sur macOS ou Linux, ça ressemble à ça :

export ANTHROPIC_API_KEY="votre_cle_api"

Sur Windows PowerShell :

$env:ANTHROPIC_API_KEY="votre_cle_api"

Quand je bosse sur un projet local, j’utilise souvent un fichier .env. C’est pratique, surtout avec plusieurs projets ou plusieurs environnements. Dans ce cas, j’installe aussi python-dotenv :

pip install python-dotenv

Puis je mets la clé dans un fichier .env à la racine du projet :

ANTHROPIC_API_KEY=votre_cle_api

Et je la charge au démarrage du script :

from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()

client = Anthropic()

print("Client Claude prêt")

Le point important, c’est que Anthropic() récupère automatiquement la clé depuis ANTHROPIC_API_KEY. Simple, propre, maintenable.

Dernier réflexe à avoir : je vérifie toujours le nom exact du modèle dans la console ou la documentation Anthropic. Les noms évoluent, les versions changent, et une erreur de modèle peut vous faire perdre du temps bêtement.

Prérequis	À quoi ça sert
Python 3.9 ou plus	Faire tourner le code Python compatible avec le SDK.
Compte Claude	Accéder à la console Anthropic et gérer l’usage API.
Clé API	Authentifier vos appels vers Claude.
SDK anthropic	Utiliser l’API Claude proprement depuis Python.
Variable ANTHROPIC_API_KEY	Éviter de mettre la clé directement dans le code.

Comment faire un premier appel API ?

Le premier appel se fait avec client.messages.create(), en précisant le modèle, max_tokens et une liste messages qui commence par un message utilisateur.

La logique est simple. Avec la Messages API, j’envoie une conversation structurée à Claude. Chaque message a un rôle, par exemple user, et un contenu, avec content. Claude traite cette conversation et renvoie un objet Message, dans lequel je récupère le texte de réponse.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=300,
    messages=[
        {
            "role": "user",
            "content": "Résume cette règle business en trois phrases : un client premium peut être remboursé sous 48h si sa commande a plus de 7 jours de retard, sauf si le retard vient d'une adresse incorrecte fournie par le client."
        }
    ]
)

print(response.content[0].text)

Le point important ici, c’est que messages est une liste. Même si vous n’avez qu’une seule question, vous envoyez quand même une liste avec un premier message. C’est ce format qui permet ensuite d’ajouter de l’historique, des relances, des corrections, bref une vraie conversation.

max_tokens mérite aussi deux minutes d’attention. Ce n’est pas une cible vague du genre “réponds à peu près en 300 tokens”. C’est un plafond strict de sortie. Si Claude atteint cette limite, la réponse peut être coupée. Sur des résumés courts, 300 est largement suffisant. Sur une analyse longue, il faut prévoir plus.

Honnêtement, sur des cas clients, les premiers bugs viennent souvent de deux endroits. Un mauvais format de messages, par exemple un dictionnaire mal placé, ou un model mal renseigné. C’est rarement un problème “d’IA”. C’est souvent juste un appel API qui n’a pas exactement la forme attendue.

• model : C’est le modèle Claude que vous appelez, et son nom doit être exact.
• max_tokens : C’est la limite maximale de tokens générés en sortie, pas une longueur souhaitée.
• messages : C’est la conversation envoyée à Claude, avec au minimum un message user contenant le texte à traiter.

Comment lire la réponse de Claude ?

La réponse de Claude est un objet Message typé, et dans la majorité des cas je lis le texte avec response.content[0].text.

Ce point est important parce que Claude ne renvoie pas juste une chaîne de caractères brute. Il renvoie un objet structuré, avec des champs utiles pour comprendre ce qui s’est passé, surveiller les coûts, et éviter les mauvaises surprises en production.

Le champ à regarder en premier, c’est content. C’est une liste de blocs. Le plus courant, c’est un bloc TextBlock, qui contient le texte dans sa propriété text. Donc oui, ça paraît un peu plus verbeux qu’un simple response.text, mais c’est volontaire. Claude peut renvoyer plusieurs types de contenus selon les usages.

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=300,
    messages=[
        {"role": "user", "content": "Explique les tokens en une phrase."}
    ]
)

text = response.content[0].text

print("Texte :", text)
print("Stop reason :", response.stop_reason)
print("Tokens entrée :", response.usage.input_tokens)
print("Tokens sortie :", response.usage.output_tokens)

Le champ stop_reason mérite vraiment votre attention. Quand il vaut end_turn, Claude a terminé sa réponse normalement. Quand il vaut max_tokens, ça veut dire que la réponse a été coupée parce que la limite de tokens de sortie était trop basse. En local, ça se voit vite. En production, ça peut créer des réponses incomplètes, des JSON cassés, ou des emails qui s’arrêtent au milieu. J’ai déjà vu ça chez un client sur une automatisation support, et le problème n’était pas le prompt. C’était juste max_tokens trop serré.

Le champ usage sert à piloter l’intégration. Il donne les tokens d’entrée et de sortie. Les tokens, ce sont les morceaux de texte que le modèle lit et génère. Avec ça, je peux estimer les coûts, repérer les prompts trop longs, optimiser le contexte, et voir si une fonctionnalité devient trop chère à grande échelle.

Si on ne loggue pas ces champs dès le début, on pilote l’intégration à l’aveugle. Ça marche pendant les tests, puis dès qu’il y a du volume, on ne sait plus pourquoi ça coûte cher, pourquoi ça coupe, ou pourquoi certaines réponses sont bizarres.

Champ	Utilité
id	Identifiant unique de la réponse, utile pour les logs et le support.
type	Type d’objet retourné, généralement message.
role	Rôle de l’émetteur, souvent assistant pour la réponse de Claude.
content	Liste de blocs de contenu, souvent des TextBlock, où se trouve le texte.
model	Modèle utilisé pour générer la réponse.
stop_reason	Raison de l’arrêt, comme end_turn ou max_tokens.
stop_sequence	Séquence personnalisée qui a arrêté la génération, si vous en avez défini une.
usage	Tokens consommés en entrée et en sortie, utile pour coûts et optimisation.

À quoi sert un system prompt ?

Un system prompt sert à fixer le rôle, le contexte et les contraintes que Claude doit respecter pendant l’échange. C’est la consigne de fond, celle qui dit à Claude “tu travailles comme ça”, avant même de lire la demande utilisateur.

Dans l’API Claude, le system prompt se passe dans le paramètre system de messages.create(). Il est séparé de la liste messages, qui elle reste dédiée aux échanges entre l’utilisateur et l’assistant. C’est important, parce que sinon on finit vite avec des prompts illisibles, où les règles permanentes et les demandes du moment sont toutes mélangées.

import anthropic

client = anthropic.Anthropic(api_key="VOTRE_CLE_API")

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=800,
    system=(
        "Tu es un relecteur expert de code Python. "
        "Tu corriges le code fourni par l'utilisateur. "
        "Tu ne réponds que par du code Python valide. "
        "Tu n'expliques jamais les changements."
    ),
    messages=[
        {
            "role": "user",
            "content": "Corrige ce code :\n\ndef add(a,b)\n    return a + b"
        }
    ]
)

print(response.content[0].text)

Ici, Claude reçoit un rôle clair : relecteur de code Python. Il reçoit aussi une contrainte très nette : répondre uniquement avec du code, sans explication. C’est typiquement le genre de règle que je mets dans le system, parce qu’elle doit rester stable sur plusieurs appels.

Le system prompt a une autorité forte sur la conversation. Ça ne veut pas dire qu’il est magique. Si votre application exige du JSON strict, du SQL sans danger, ou un format métier précis, il faut quand même valider côté application. J’ai déjà vu des équipes mettre “réponds toujours en JSON” et considérer que ça suffisait. Non. Ça aide beaucoup, mais ça ne remplace pas un parseur, des contrôles, ou des garde-fous.

Les bonnes contraintes sont souvent simples et concrètes :

• Format de sortie : Réponds uniquement en JSON valide.
• Rôle métier : Tu es un analyste data spécialisé en e-commerce.
• Ton : Réponds de manière directe, courte et professionnelle.
• Interdictions : Ne donne jamais de conseil juridique définitif.
• Contexte applicatif : Les réponses seront affichées dans une interface client.

Ma règle pratique est simple : Je mets les règles permanentes dans le system prompt, et les demandes ponctuelles dans le message user. Comme ça, le prompt reste maintenable, et quand quelque chose dérape, on sait où regarder.

Comment préparer l’intégration en production ?

Pour intégrer Claude en production, il faut gérer les clés proprement, surveiller les tokens, prévoir les erreurs, utiliser le streaming si l’expérience utilisateur le demande et structurer les prompts comme du vrai code applicatif.

Je vois souvent le même piège chez les équipes qui passent du prototype au vrai produit : le script marche en local, puis tout devient fragile dès qu’on a du trafic, des utilisateurs, des logs, des coûts et des erreurs réseau. Le SDK Python aide beaucoup parce qu’il donne une interface claire, des objets typés, et selon la configuration utilisée, des mécanismes utiles comme les retries côté client. Un retry, c’est juste une nouvelle tentative automatique quand une requête échoue temporairement, par exemple sur un timeout.

Les bases à poser sont simples, mais elles changent tout :

• Ne jamais hardcoder la clé API dans le code. Elle doit venir d’une variable d’environnement ou d’un gestionnaire de secrets.
• Définir des limites de tokens pour éviter les réponses trop longues et les coûts imprévus.
• Logger stop_reason pour comprendre pourquoi Claude s’est arrêté.
• Logger usage pour suivre les tokens consommés en entrée et en sortie.
• Gérer les erreurs réseau, les timeouts, les erreurs d’authentification et les réponses applicatives inattendues.
• Tester les prompts système comme on teste une règle métier, parce qu’un mauvais prompt en production peut coûter cher.
• Surveiller les coûts par fonctionnalité, pas juste au global.

Le streaming mérite aussi d’être prévu assez tôt. Il permet d’afficher la réponse progressivement au lieu d’attendre que toute la génération soit terminée. Pour un chat, c’est souvent indispensable. Pour une génération longue, ça donne une impression de rapidité et ça évite l’écran figé. Pas besoin de l’utiliser partout, mais il faut savoir où il améliore vraiment l’expérience.

Application Python
  - Routes API ou backend web
  - Authentification utilisateur

Service Claude
  - Client SDK Anthropic
  - Gestion des timeouts et retries
  - Appels simples ou streaming

Gestion des prompts
  - Prompts système versionnés
  - Templates testés
  - Variables contrôlées

Logs et monitoring
  - stop_reason
  - usage
  - latence
  - erreurs
  - coût estimé

J’aime bien isoler Claude dans un service dédié. Ça évite d’avoir des prompts dispersés partout dans le code. Le jour où vous changez de modèle, de stratégie de coût ou de format de réponse, vous ne cassez pas toute l’application.

Usage	Quand l’utiliser	Points à surveiller
Usage simple	Scripts internes, prototypes, tâches courtes.	Clé API, limite de tokens, erreurs basiques.
Usage streaming	Chat, longues réponses, interface utilisateur interactive.	Gestion de l’affichage progressif, coupures réseau, annulation utilisateur.
Usage production	Produit client, automatisation critique, volume régulier.	Logs, monitoring, coûts, retries, tests de prompts, sécurité des secrets.

On démarre proprement avec Claude maintenant ?

Utiliser l’API Claude en Python, ce n’est pas compliqué. Le SDK anthropic fait une bonne partie du travail : installation simple, appel clair avec client.messages.create(), réponse typée, accès direct au texte, suivi des tokens. Là où il faut être sérieux, c’est sur la structure des messages, le system prompt, la gestion de max_tokens, le suivi de stop_reason et l’usage en production. J’ai vu trop d’intégrations IA démarrer vite puis devenir floues au bout de deux semaines. Si vous posez ces bases dès le départ, vous gagnez une intégration Claude plus fiable, plus maintenable et plus utile pour votre business.

FAQ

• Quelle version de Python faut-il pour utiliser l’API Claude ?
  Il faut utiliser Python 3.9 ou plus. C’est la base recommandée pour travailler proprement avec le SDK Python anthropic et éviter les soucis de compatibilité.
• Où mettre ma clé API Claude en Python ?
  Je vous conseille de la mettre dans une variable d’environnement ANTHROPIC_API_KEY ou dans un fichier .env chargé avec python-dotenv. Évitez de la mettre directement dans le code, surtout si le projet part sur Git.
• Comment récupérer le texte généré par Claude ?
  Après un appel à client.messages.create(), le texte se récupère généralement avec response.content[0].text. Le champ content est une liste de blocs, pas une simple chaîne de caractères.
• À quoi sert stop_reason dans la réponse ?
  stop_reason indique pourquoi Claude s’est arrêté. Si la valeur indique une fin normale comme end_turn, tout va bien. Si la réponse est coupée par la limite max_tokens, il faut ajuster votre plafond ou votre prompt.
• Quand utiliser le streaming avec l’API Claude ?
  Le streaming est utile quand vous voulez afficher la réponse progressivement, par exemple dans une interface de chat ou une génération longue. Pour un script simple ou un traitement back-office, un appel classique suffit souvent.

 

 

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 créer une usine à gaz. Avec webAnalyste et Formations Analytics, j’ai travaillé pour 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 des workflows IA ou cadrer un vrai usage data dans votre business, contactez-moi.