Claude API : premiers appels (Messages API 2026)

À la fin de ce tutoriel, vous ferez vos premiers appels à la Claude API (Messages API) : hygiène de la clé, un curl minimal, un script Python (anthropic), un lab SRE (system prompt + CrashLoopBackOff), le streaming, le choix Haiku / Sonnet / Opus, puis un pattern d’intégration CI sans jamais hardcoder de secret.

Niveau : Débutant → Intermédiaire · Temps estimé : 45–60 min · Versions : SDK anthropic Python récent · Messages API POST /v1/messages · Dernière vérification : 2026-09-11

← Précédent : Claude Projects & Artifacts · → Suivant : Prompt engineering avec Claude · Hub : IA parcours DevOps 2026

Statut : HOLD — draft only (ne pas publier sur WordPress)

Prérequis

• [ ] Compte Anthropic Console avec accès API et budget / spend limits configurés
• [ ] Une clé API stockée en variable d’environnement ANTHROPIC_API_KEY (jamais dans le dépôt)
• [ ] Python 3.10+, venv, pip ; curl et jq pour le lab HTTP
• [ ] Notions HTTP JSON et secrets CI (GitHub Actions / GitLab CI)
• [ ] Coût estimé : quelques centimes avec claude-haiku-4-5 ; plafond Console avant le lab

Sans clé : lisez le code, n’appelez pas l’API.

Ce que nous allons construire

Lab Claude API (Messages 2026)
  ├── Secret : ANTHROPIC_API_KEY (env / CI secret)
  ├── cURL  → POST https://api.anthropic.com/v1/messages
  ├── Python SDK → client.messages.create(...)
  ├── System prompt SRE + historique multi-tour
  ├── usage.input_tokens / output_tokens + stop_reason
  ├── stream=True (aperçu) + choix Haiku / Sonnet / Opus
  └── Pattern CI runbook (secret injecté, jamais loggé)

(Schéma — alt : « Flux Claude API : clé secrète, cURL/SDK, Messages API, tokens et CI ».)

Étape 1 — Pourquoi l’API Claude pour un DevOps

L’UI Claude (Projects, Artifacts) accélère l’exploration. L’API devient utile dès que vous automatisez : résumé de logs en pipeline, assistant runbook, bot Slack, ou revue de diff hors navigateur.

Besoin	UI Claude	Claude API
Lab manuel / atelier	Excellent	Surdimensionné
Script / cron / CI	Limité	Cible
Secrets & quotas	Compte perso	Workspaces + spend limits
Historique	Session produit	Stateless : vous renvoyez les messages

Angle Elastic Hayway 2026 : Claude = service HTTP facturé au token, même hygiène qu’un cloud provider (clé, budget, observabilité).

Étape 2 — Clé API et hygiène secrets

1. Créez une clé dans la Console Anthropic (workspace dédié « lab » si possible).
2. Exportez-la uniquement en local :

export ANTHROPIC_API_KEY="sk-ant-…votre-clé…"   # jamais dans Git
# Vérifiez la présence sans afficher la valeur :
test -n "$ANTHROPIC_API_KEY" && echo "clé chargée" || echo "clé absente"

Règles non négociables :

• Pas de clé dans le code, les captures d’écran, les tickets Jira ou les logs CI
• Rotation après fuite ; scopes / workspaces séparés lab vs prod
• Budget et spend limits Console avant le premier script en boucle
• En CI : secret GitHub Actions / variable masquée GitLab — jamais echo $ANTHROPIC_API_KEY

Étape 3 — Premier appel cURL

Endpoint de base : https://api.anthropic.com. Ressource : POST /v1/messages.

Headers obligatoires en pratique :

• x-api-key: $ANTHROPIC_API_KEY (ou schéma Bearer selon client)
• anthropic-version: 2023-06-01
• content-type: application/json

curl -s https://api.anthropic.com/v1/messages 
  -H "x-api-key: $ANTHROPIC_API_KEY" 
  -H "anthropic-version: 2023-06-01" 
  -H "content-type: application/json" 
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "En une phrase : qu'''est-ce qu'''un CrashLoopBackOff ?"}
    ]
  }' | jq '{id, model, stop_reason, usage, text: .content[0].text}'

max_tokens est obligatoire. La réponse contient content[] (blocs type=text), usage.input_tokens / usage.output_tokens, et stop_reason (souvent end_turn). Sans clé : gardez le JSON prêt, n’exécutez pas.

Étape 4 — SDK Python Messages API

python3 -m venv .venv && source .venv/bin/activate
pip install -U anthropic

import anthropic

client = anthropic.Anthropic()  # lit ANTHROPIC_API_KEY

msg = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=256,
    messages=[
        {
            "role": "user",
            "content": "Liste 3 commandes kubectl utiles pour un pod en CrashLoopBackOff.",
        }
    ],
)

print(msg.content[0].text)
print(msg.usage.input_tokens, msg.usage.output_tokens, msg.stop_reason)

Le SDK gère retries et JSON. En runbook, loggez uniquement model, usage et un request_id — jamais la clé ni un prompt contenant des secrets d’infra.

Étape 5 — System prompt + multi-tour + usage tokens

Le paramètre system est top-level : ne placez pas de message role: "system" dans messages. Les tours alternent user / assistant. L’API est stateless : pour un dialogue, renvoyez tout l’historique.

Lab mini DevOps (SRE + CrashLoopBackOff) — exécutez seulement si la clé est chargée :

import anthropic
import os

if not os.environ.get("ANTHROPIC_API_KEY"):
    raise SystemExit("Pas de clé — relisez le code sans appeler l’API.")

client = anthropic.Anthropic()

system = (
    "Tu es un SRE senior. Tu expliques kubectl et la lecture de logs "
    "de façon concise, avec commandes concrètes et risques (prod)."
)

messages = [
    {
        "role": "user",
        "content": (
            "Un Deployment api-checkout a un pod en CrashLoopBackOff "
            "depuis 12 minutes. Par quoi commencer ?"
        ),
    }
]

r1 = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=512,
    system=system,
    messages=messages,
)
print(r1.content[0].text)
print("tokens:", r1.usage.input_tokens, r1.usage.output_tokens)

messages.append({"role": "assistant", "content": r1.content[0].text})
messages.append(
    {
        "role": "user",
        "content": "Donne la séquence kubectl describe puis logs --previous.",
    }
)

r2 = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=512,
    system=system,
    messages=messages,
)
print(r2.content[0].text)
print("stop:", r2.stop_reason, "out:", r2.usage.output_tokens)

Surveillez usage à chaque tour : l’historique renvoyé recompte les tokens d’entrée. Pour estimer avant coup : Token Counting API (docs Anthropic).

Étape 6 — Streaming et choix de modèle (Haiku / Sonnet / Opus)

Streaming bref (stream=True) pour un TTY ou un bot :

with client.messages.stream(
    model="claude-haiku-4-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Résume CrashLoopBackOff en 2 phrases."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Modèle (ID lab 2026)	Profil	Prix approx. (input / output / MTok)
claude-haiku-4-5	Rapide / cheap — défaut labs	~$1 / ~$5
claude-sonnet-5	Équilibre qualité / coût	~$2 / ~$10
claude-opus-5	Puissant / coût+	~$5 / ~$25

Pinnez l’ID en CI (évitez un « latest » flou). Volume asynchrone : Message Batches (~50 % off). Alternatives : Bedrock, Vertex AI, Foundry — logique Messages, facturation/IAM du cloud.

Étape 7 — Intégrer en CI / runbook (pattern)

Pattern GitHub Actions (illustratif — aucun secret réel) :

# .github/workflows/claude-runbook.yml (extrait)
jobs:
  sre-hint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install anthropic
      - name: Runbook hint (Haiku)
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: python scripts/sre_crashloop_hint.py

Checklist ops :

• Secret nommé, rotation documentée ; job en échec si secret absent
• Modèle = Haiku pour hints CI ; Sonnet/Opus hors chemin critique coût
• Timeout job + plafond tokens ; pas de dump du body complet si logs sensibles
• Métriques : input_tokens / output_tokens vers votre dashboard

Lab concret DevOps

Dans votre dépôt lab API, créez hello_messages.py qui lit la clé depuis l’environnement, envoie un prompt borné (« résume ce runbook fictif en 5 puces, staging only »), affiche le texte et les usage tokens. Vérifiez qu’aucune clé n’est loggée. Committez script + README sans secrets. Enchaînez ensuite un second appel avec un system prompt d’incertitude (« marque HYPOTHÈSE »).

mkdir -p ~/lab-claude-api && cd ~/lab-claude-api && git init
printf '%s
' '# Lab API Claude' 'Clé via env ANTHROPIC_API_KEY' > README.md
echo '.env' >> .gitignore
git add . && git commit -m "chore: cadre lab API"

Erreurs fréquentes

Symptôme	Cause probable	Correctif
401 / authentication	Clé absente, expirée, mauvais header	Vérifier ANTHROPIC_API_KEY et x-api-key
400 sur max_tokens	Champ oublié	Toujours envoyer max_tokens
System ignoré / bizarre	role: system dans messages	Utiliser le paramètre top-level system
Contexte « perdu »	API stateless	Renvoyer l’historique complet
Facture surprise	Sonnet/Opus en boucle CI	Haiku + spend limits + Batches
Fuite de clé	echo / commit / log debug	Secret store + rotation immédiate

Quiz (5 questions)

1. L’endpoint Messages API est :
– A. GET /v1/complete
– B. POST /v1/messages
– C. PUT /v1/chat

2. Où placer les instructions SRE durables ?
– A. Uniquement dans le premier user
– B. Paramètre top-level system
– C. Header X-System-Prompt

3. Pourquoi l’API est-elle dite stateless ?
– A. Elle efface la clé après chaque appel
– B. Elle ne mémorise pas la conversation : vous renvoyez l’historique
– C. Elle refuse le streaming

4. Pour un lab CI low-cost en 2026, on pinne souvent :
– A. claude-opus-5 uniquement
– B. claude-haiku-4-5
– C. Un modèle sans max_tokens

5. En GitHub Actions, la clé doit vivre dans :
– A. Un fichier .env commité
– B. secrets.ANTHROPIC_API_KEY (ou équivalent masqué)
– C. Les logs set -x

Réponses : 1‑B · 2‑B · 3‑B · 4‑B · 5‑B

Compléments opérationnels

Standard de brief réutilisable

Pour claude-api-premiers-appels, adoptez un brief unique partagé par l’équipe. Il contient toujours cinq champs : objectif mesurable, contexte borné (lab/staging), liste blanche de fichiers ou ressources, interdits explicites (secrets, réseau, prod), et definition of done exécutable (commande de test ou checklist). Sans ces champs, l’outil improvisera — parfois avec élégance, souvent hors périmètre.

Stockez les briefs gagnants sous briefs/claude-api-premiers-appels/ dans un dépôt de documentation interne. Chaque brief cite le commit de référence et le modèle utilisé. Au troisième succès comparable, ouvrez une PR qui transforme le brief en rule, Skill ou slash command. Voir ai-skills-concept, claude-skills-instructions et evaluer-qualite-skill.

Revue de diff comme compétence P0

La vitesse d’un agent n’a aucune valeur si personne ne sait lire un diff. Instituez une règle simple : aucun apply massif sans parcours hunk par hunk. Posez-vous trois questions : ce changement est-il demandé ? est-il testé ? est-il réversible ? Si une réponse est non, refusez ou exigez un plan plus petit.

En atelier, faites commenter un diff à voix haute pendant cinq minutes. Les juniors apprennent ainsi le vocabulaire du refus. Reliez cette pratique à ai-code-review-pr et aux workflows ai-agent-workflows.

Sécurité continue

Les surfaces claude-api-premiers-appels multiplient les occasions d’injection et de fuite. Traitez tickets, README upstream, logs et ressources MCP comme des données non fiables. Séparez instructions et données. Allowlist tools. Confirmation humaine avant mutation. Guide : ai-prompt-injection-securite, mcp-servers-devops, claude-code-mcp.

Secrets : variables d’environnement de session, gestionnaire d’équipe, rotation, jamais de commit. Si un secret fuit dans un chat vendor, supposez-le compromis et rotatez.

Coûts, modèles et mode dégradé

Documentez un mapping fast/strong et un soft-cap mensuel dans la stack perso. OpenRouter peut aider à basculer — openrouter-multi-modeles. Le local (ollama-llm-locaux + continue-dev) sert de mode dégradé ou de bac à sable confidentialité.

Surveillez les changements silencieux de modèle par défaut : une régression de qualité est souvent un routing vendor, pas « l’équipe qui a oublié comment prompter ».

FAQ

Faut-il le SDK Python pour démarrer ?
Non. curl + JSON suffit pour valider auth et modèle. Le SDK accélère streaming, erreurs et intégration scripts.

Puis-je mettre role: "system" dans messages ?
Non pour ce flux Messages : utilisez le champ system top-level. Les messages alternent user/assistant.

Comment maîtriser les coûts ?
Haiku pour labs/CI, max_tokens serré, Token Counting avant gros contextes, Batches pour l’asynchrone, spend limits Console, et métriques usage dans vos dashboards.

Bedrock / Vertex / Foundry remplacent-ils l’API directe ?
Ce sont des alternatives d’hébergement (IAM, régions, facturation cloud). Le contrat Messages reste proche.

Que logger en production ?
model, tokens, latence, stop_reason, corrélation request — jamais la clé, et attention au contenu (PII, secrets kube).

Points clés

• Messages API = POST /v1/messages + headers version / clé / JSON
• ANTHROPIC_API_KEY hors Git ; secrets CI uniquement
• max_tokens obligatoire ; system top-level ; historique renvoyé à chaque tour
• Labs : claude-haiku-4-5 ; monter vers Sonnet/Opus selon besoin
• Lire content[], usage, stop_reason ; streaming pour UX interactive
• CI = pattern secret + plafond tokens + pas de log de clé

Pour aller plus loin

• Docs Anthropic (Messages, streaming, Token Counting, Batches) — site docs officiel
• Claude Projects & Artifacts
• Prompt engineering avec Claude
• Claude Code : démarrer
• Claude vs GPT
• Hub : IA parcours DevOps 2026

Maillage série IA Outils 2026

← Précédent	Claude Projects & Artifacts
→ Suivant	Prompt engineering avec Claude
Hub	IA parcours DevOps 2026
Aussi	Claude Code démarrer · Claude vs GPT