Ce que vous saurez faire à la fin

Créer votre clé API Anthropic et la sécuriser
Installer le SDK Python et faire votre premier appel
Gérer conversations multi-tours et streaming
Utiliser Tool Use pour connecter Claude à vos fonctions
Activer le prompt caching pour diviser vos coûts par 10

Durée : 1 heure. Pré-requis : Python 3.10+, carte de paiement pour la clé API, 5 USD de crédit Anthropic pour commencer.

Étape 1 — Créer un compte Anthropic et obtenir une clé

Allez sur console.anthropic.com. Créez un compte (email + mot de passe ou SSO Google).
Dans le menu latéral : API Keys > Create Key.
Nom : « dev-machine ». Copiez la clé immédiatement (affichée une seule fois). Format : sk-ant-api03-xxxxxxxxxxxxxxxxxxxx....
Ajoutez 5 USD de crédit : Billing > Add to balance.
Activez les alertes de consommation : Billing > Usage limits > définir un seuil mensuel à 10 USD pour commencer.

Étape 2 — Stocker la clé en variable d’environnement

JAMAIS dans le code source. JAMAIS commit dans Git.

Linux / Mac :

# Dans ~/.zshrc ou ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxxxx"

# Recharger
source ~/.zshrc

Windows PowerShell (persistant) :

[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-api03-...', 'User')
# Relancez PowerShell

Pour un projet : fichier .env à la racine (ajoutez dans .gitignore) :

ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxx

Étape 3 — Installer le SDK

pip install anthropic==0.42.0 python-dotenv

Étape 4 — Premier appel en 6 lignes

Créez premier_appel.py :

from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv()

client = Anthropic()

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explique Bayes en 3 phrases."}]
)
print(msg.content[0].text)
print("Tokens:", msg.usage.input_tokens, "in /", msg.usage.output_tokens, "out")

Exécutez : python premier_appel.py.
Vous obtenez une réponse + le coût en tokens.
Coût : ~0,001 USD pour cet appel.

Étape 5 — Choisir le bon modèle

claude-opus-4-7       le plus intelligent, 15 USD in / 75 USD out / M tokens
claude-sonnet-4-6     équilibre recommandé, 3 USD / 15 USD
claude-haiku-4-5      ultra rapide, 0,25 USD / 1,25 USD

Choix:
- Tâche simple (classification, extraction): Haiku
- Raisonnement moyen (résumé, rédaction): Sonnet
- Code complexe, raisonnement profond: Opus

Étape 6 — Conversation multi-tours

historique = []

def demander(user_text):
    historique.append({"role": "user", "content": user_text})
    r = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=2048,
        system="Tu es un assistant data science concis. Réponds en français.",
        messages=historique,
    )
    reponse = r.content[0].text
    historique.append({"role": "assistant", "content": reponse})
    return reponse

print(demander("Qu'est-ce qu'un intervalle de confiance à 95% ?"))
print(demander("Montre-moi un exemple Python avec scipy."))

Étape 7 — Streaming (token par token)

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Rédige une intro de 200 mots sur le Sahel."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print()

Utile pour les chatbots où l’utilisateur voit la réponse apparaître au fur et à mesure.

Étape 8 — Tool Use : faire appeler vos fonctions

import json

tools = [{
    "name": "get_weather",
    "description": "Météo actuelle d'une ville",
    "input_schema": {
        "type": "object",
        "properties": {"ville": {"type": "string"}},
        "required": ["ville"],
    },
}]

def ma_fonction_meteo(ville):
    return {"temp_C": 28, "humidite": 75, "description": "Ensoleillé"}

def chat_avec_outils(question):
    messages = [{"role": "user", "content": question}]
    for _ in range(5):
        r = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            tools=tools,
            messages=messages,
        )
        messages.append({"role": "assistant", "content": r.content})
        
        if r.stop_reason == "end_turn":
            for bloc in r.content:
                if hasattr(bloc, "text"):
                    return bloc.text
        
        tool_results = []
        for bloc in r.content:
            if bloc.type == "tool_use":
                if bloc.name == "get_weather":
                    resultat = ma_fonction_meteo(**bloc.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": bloc.id,
                        "content": json.dumps(resultat),
                    })
        messages.append({"role": "user", "content": tool_results})

print(chat_avec_outils("Quelle météo à Dakar ?"))

Étape 9 — Prompt caching (90 % d’économies)

Cache ephemeral : valide 5 minutes, renouvelé à chaque usage.
Idéal pour : system prompt stable, contexte répété entre appels.

GROS_CONTEXTE = open("guidelines.txt").read()  # ex: 5000 tokens

r = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": GROS_CONTEXTE,
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[{"role": "user", "content": "Résume en 3 points"}],
)

print("Cache read:", r.usage.cache_read_input_tokens)  # 0 au 1er appel, >0 après

Prix des tokens lus du cache : 10 % du prix normal. Sur gros system prompts répétés : économie immédiate.

Étape 10 — Gestion d’erreurs avec retry

from anthropic import APIConnectionError, RateLimitError, APIStatusError
import time

def call_avec_retry(prompt, max_retries=3):
    for essai in range(max_retries):
        try:
            r = client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=512,
                messages=[{"role": "user", "content": prompt}],
            )
            return r.content[0].text
        except RateLimitError:
            attente = 2 ** essai
            print(f"Rate limit, retry dans {attente}s")
            time.sleep(attente)
        except APIStatusError as e:
            print(f"Erreur API {e.status_code}: {e.message}")
            if e.status_code >= 500:
                time.sleep(2 ** essai)
            else:
                raise
    raise Exception("Max retries atteint")

Étape 11 — Vision (analyser une image)

import base64

with open("facture.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

r = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "image",
                "source": {
                    "type": "base64",
                    "media_type": "image/jpeg",
                    "data": image_data,
                },
            },
            {"type": "text", "text": "Extrait le montant TTC, la date et le nom du fournisseur en JSON."}
        ],
    }],
)
print(r.content[0].text)

Étape 12 — PDF (extraction de documents)

with open("contrat.pdf", "rb") as f:
    pdf_data = base64.b64encode(f.read()).decode("utf-8")

r = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "document",
                "source": {
                    "type": "base64",
                    "media_type": "application/pdf",
                    "data": pdf_data,
                },
            },
            {"type": "text", "text": "Résume ce contrat en 150 mots et liste 3 risques."}
        ],
    }],
)

Étape 13 — Contrôle de coût

def estimer_cout(usage, model="claude-sonnet-4-6"):
    prix = {
        "claude-opus-4-7": (15, 75),
        "claude-sonnet-4-6": (3, 15),
        "claude-haiku-4-5": (0.25, 1.25),
    }
    p_in, p_out = prix[model]
    cout_in = (usage.input_tokens / 1_000_000) * p_in
    cout_out = (usage.output_tokens / 1_000_000) * p_out
    return cout_in + cout_out

cout = estimer_cout(msg.usage)
print(f"Coût: ${cout:.4f} = {cout * 630:.1f} FCFA")

Étape 14 — Logging et observabilité

import logging
import json

logging.basicConfig(filename="claude.log", level=logging.INFO)

def tracer_appel(prompt, reponse, usage):
    logging.info(json.dumps({
        "ts": time.time(),
        "prompt_chars": len(prompt),
        "response_chars": len(reponse),
        "input_tokens": usage.input_tokens,
        "output_tokens": usage.output_tokens,
        "cache_read": usage.cache_read_input_tokens or 0,
        "cost_usd": estimer_cout(usage),
    }))

Étape 15 — Checklist de production

✓ Clé API en variable d'environnement, jamais dans le code
✓ Modèle choisi selon la tâche (Haiku pour simple, Sonnet/Opus pour complexe)
✓ System prompt avec cache_control sur parties stables
✓ Retry avec backoff exponentiel sur 429 et 5xx
✓ Gestion d'erreurs explicite (APIStatusError, RateLimitError)
✓ Logging JSON de chaque appel (tokens, coût, latence)
✓ Limite mensuelle de budget définie dans la console
✓ Monitoring des coûts (dashboard GA4/Superset/Metabase)
✓ Tests unitaires sur vos prompts (snapshot testing)

Étape 1 — Préparer un environnement Python isolé

Travailler dans un environnement virtuel évite les conflits de versions sur votre poste. Sur un laptop Tecno ou un MacBook, ouvrez un terminal et créez un dossier projet dédié. Cette discipline rend votre code reproductible quand vous le partagez avec un collègue à Abidjan ou Casablanca.

mkdir claude-quickstart && cd claude-quickstart
python3 -m venv .venv
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows PowerShell

Le prompt doit afficher (.venv) en début de ligne : c’est le signal que vous êtes dans l’environnement isolé. Sans cette indication, vous installerez les paquets dans le Python global, source de bugs invisibles plus tard.

Étape 2 — Installer le SDK officiel anthropic

Anthropic publie un SDK Python officiel maintenu activement. Il gère la signature des requêtes, le streaming, les retries, et les types Pydantic des réponses. Ne réinventez pas la roue avec requests brut.

pip install anthropic

Vérifiez la version installée. À jour début 2026, la branche 0.x couvre les modèles Claude Sonnet et Opus actuels. Si la commande pip ne trouve pas le paquet, vérifiez que vous êtes bien dans le venv et que pip pointe sur Python 3.

Étape 3 — Récupérer une clé API et la stocker hors du code

Créez un compte sur la console Anthropic, générez une clé API depuis la section API Keys, et copiez-la une seule fois (elle ne sera plus affichée). Stockez-la dans un fichier .env à la racine du projet, jamais en dur dans le code source.

# .env
ANTHROPIC_API_KEY=sk-ant-...

Ajoutez .env à votre .gitignore avant le premier commit. Une clé poussée par erreur sur GitHub public est compromise en quelques minutes par les bots de scraping. En cas d’oubli, révoquez immédiatement la clé depuis la console.

Étape 4 — Premier appel : le hello world

Créez un fichier hello.py avec le code minimal qui appelle Claude. Ce code installe la fondation que vous étendrez ensuite avec streaming, outils, et conversation multi-tours.

import os
from dotenv import load_dotenv
from anthropic import Anthropic

load_dotenv()
client = Anthropic()  # lit ANTHROPIC_API_KEY automatiquement

reponse = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Bonjour Claude, présente-toi en deux phrases."}]
)
print(reponse.content[0].text)

Installez aussi python-dotenv (pip install python-dotenv) puis lancez python hello.py. La première réponse arrive en 2 à 4 secondes selon votre connexion. Test concluant : un texte cohérent affiché dans le terminal, sans erreur d’authentification.

Étape 5 — Comprendre la structure de la réponse

L’objet reponse contient plusieurs champs utiles : id, model, role, content (liste de blocs), stop_reason, usage (tokens consommés). Le champ usage est essentiel pour piloter le coût en production.

print(reponse.id)
print(reponse.usage.input_tokens, "input")
print(reponse.usage.output_tokens, "output")
print(reponse.stop_reason)  # "end_turn", "max_tokens", "tool_use", etc.

Notez les tokens consommés sur vos premiers appels pour calibrer votre budget. À titre indicatif, une conversation courte tient en quelques centaines de tokens, un résumé d’article long en quelques milliers.

Étape 6 — Activer le streaming pour une expérience fluide

Sur une 4G dakaroise, attendre 4 secondes une réponse complète crée une perception de lenteur. Le streaming affiche le texte caractère par caractère, comme dans l’interface chat. Cela améliore le ressenti même si le temps total reste identique.

with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explique le streaming en 3 phrases."}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
print()

Le texte apparaît progressivement. Si vous bâtissez une interface web, branchez ce flux sur Server-Sent Events ou WebSocket pour répliquer l’effet côté navigateur.

Étape 7 — Construire une conversation multi-tours

L’API ne mémorise pas les échanges précédents. Vous devez renvoyer l’historique à chaque appel. Maintenez une liste messages que vous enrichissez à chaque tour.

messages = []
def discuter(user_text):
    messages.append({"role": "user", "content": user_text})
    r = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=messages
    )
    reply = r.content[0].text
    messages.append({"role": "assistant", "content": reply})
    return reply

print(discuter("Quels sont les 3 fleuves d'Afrique de l'Ouest ?"))
print(discuter("Et le plus long parmi eux ?"))

Le second appel garde le contexte du premier. Surveillez la taille cumulée : au-delà de quelques milliers de tokens d’historique, le coût grimpe et la fenêtre se sature. Activez le caching de prompt pour les contextes longs récurrents.

Étape 8 — Activer le prompt caching pour réduire le coût

Si vous envoyez systématiquement un long contexte (documentation produit, base de connaissances), le caching réduit jusqu’à 90 pour cent le coût des tokens en entrée pour les réutilisations dans les 5 minutes.

system_prompt = [
    {
        "type": "text",
        "text": "Vous êtes l'assistant produit de la boutique X...",  # long contexte
        "cache_control": {"type": "ephemeral"}
    }
]
r = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=system_prompt,
    messages=[{"role": "user", "content": "Question utilisateur"}]
)
print(r.usage.cache_read_input_tokens)

Mesurez le champ cache_read_input_tokens : si le second appel l’incrémente, le cache fonctionne. Sinon, vérifiez que le bloc système n’a pas changé d’un caractère entre les appels.

Étape 9 — Gérer les erreurs en production

L’API peut renvoyer plusieurs catégories d’erreur : 401 (clé invalide), 429 (rate limit), 529 (overload). Le SDK lève des exceptions typées que vous pouvez attraper proprement.

from anthropic import APIStatusError, RateLimitError

try:
    r = client.messages.create(...)
except RateLimitError:
    time.sleep(2 ** retry)  # backoff exponentiel
except APIStatusError as e:
    if e.status_code == 529:
        time.sleep(5)
    else:
        raise

Ajoutez un journal structuré (loguru ou structlog) qui capture status_code, request_id et durée. Sans cette traçabilité, débugger un incident en production devient un cauchemar trois semaines plus tard.

Étape 10 — Déployer un mini-bot conversationnel

Empaquetez les étapes 6 à 9 dans un script bot.py exécutable depuis un VPS à 4 EUR par mois (environ 2 600 FCFA). Combinez avec FastAPI pour exposer un endpoint /chat consommé par votre frontend, ou avec un cron pour des tâches batch nocturnes.

Premier déploiement réaliste : 2 à 3 heures pour un développeur Python qui suit ce tutoriel. Comptez 0,01 à 0,05 EUR par conversation courte selon le modèle, à valider avec vos propres mesures de tokens.

Récapitulatif opérationnel

Démarrer avec Claude API en Python = environnement isolé + SDK officiel + clé en .env + premier appel + compréhension de la réponse + streaming + multi-tours + prompt caching + gestion d’erreurs + déploiement. Quinze minutes pour le hello world, deux à trois heures pour un mini-bot fonctionnel.

Erreurs fréquentes à éviter

Premier piège : coller la clé API dans le code et committer sur GitHub — révocation obligatoire et perte de temps. Deuxième piège : oublier que l’API ne mémorise rien et envoyer chaque message isolé en attendant qu’il connaisse l’historique. Troisième piège : ignorer le champ usage et découvrir une facture surprise en fin de mois — instrumentez dès le premier appel.

Claude API : démarrer en 15 minutes avec Python