Accueil › Claude › API

Claude API : le guide développeur complet

L’API Claude est l’interface programmatique d’Anthropic pour accéder aux modèles Opus 4.6, Sonnet 4.6 et Haiku 4.5. Elle fonctionne en REST stateless sur api.anthropic.com/v1/messages, avec facturation au token, tool use natif, streaming SSE, batch processing et prompt caching.

Ce guide couvre tout ce qu’il faut pour intégrer Claude dans vos applications : configuration initiale, Messages API, tool use (function calling), Extended Thinking, streaming, batch processing, prompt caching, choix du modèle, optimisation des coûts, et plateformes disponibles. Exemples de code inclus.

Démarrage rapide

Créer un compte et obtenir une clé API

Rendez-vous sur console.anthropic.com. Créez un compte développeur avec votre adresse e-mail professionnelle. Ajoutez un moyen de paiement (l’API est facturée à l’usage). Générez une clé API dans « API Keys ». Stockez-la dans une variable d’environnement (ANTHROPIC_API_KEY) et ne la commitez jamais dans un dépôt de code.

Anthropic organise les clés API en workspaces (jusqu’à 100 par organisation). Chaque clé est scopée à un seul workspace, ce qui permet d’isoler les environnements (dev, staging, production) et de contrôler les dépenses par cas d’usage.

Votre premier appel API

Avec le SDK Python :

import anthropic

client = anthropic.Anthropic()  # utilise ANTHROPIC_API_KEY

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explique le RAG en 3 phrases."}
    ]
)

print(message.content[0].text)

Avec curl :

curl https://api.anthropic.com/v1/messages 
  --header "x-api-key: $ANTHROPIC_API_KEY" 
  --header "anthropic-version: 2023-06-01" 
  --header "content-type: application/json" 
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explique le RAG en 3 phrases."}
    ]
  }'

La réponse est un objet JSON contenant un tableau content avec des blocs de type text, tool_use, ou thinking.

Messages API : le cœur de l’intégration

La Messages API est l’interface principale. Vous envoyez une liste de messages (alternance user/assistant) et un prompt système optionnel. Claude génère le message suivant dans la conversation.

L’API est stateless : elle ne conserve aucun historique entre les appels. C’est à vous d’inclure l’historique complet de la conversation dans chaque requête. Cette conception rend les workflows déterministes, faciles à déboguer et scalables.

Paramètres clés : model (identifiant du modèle), max_tokens (limite de tokens en sortie), messages (historique de conversation), system (prompt système), temperature (contrôle de la créativité, 0 à 1), tools (définitions de fonctions), stream (true pour le streaming SSE).

Vous pouvez pré-remplir la réponse de Claude en ajoutant un message assistant en fin de liste. Claude continue à partir de ce point. Cette technique est utile pour forcer un format de sortie (commencer par { pour du JSON, par exemple).

Choix du modèle

Règle d’or : commencez par Sonnet 4.6 pour la plupart des cas d’usage de production. Passez à Opus 4.6 uniquement quand la qualité le justifie (raisonnement multi-étapes, bugs complexes, analyse financière). Utilisez Haiku 4.5 pour les tâches simples à grande échelle où le coût est critique.

Depuis le 13 mars 2026, Opus 4.6 et Sonnet 4.6 sont facturés au tarif unique sur toute la fenêtre de 1M tokens, sans surcoût long contexte. C’est un avantage significatif par rapport à GPT-5.4 (surcoût au-delà de 272K tokens) pour les applications qui traitent de longs documents.

Vous pouvez interroger les capacités et limites de chaque modèle via l’API Models (/v1/models), qui retourne max_input_tokens, max_tokens et un objet capabilities.

Tool Use (Function Calling)

Le tool use permet à Claude d’interagir avec des fonctions externes que vous définissez. C’est l’une des fonctionnalités les plus puissantes de l’API pour construire des agents IA.

Le principe : vous définissez vos outils en JSON Schema (nom, description, paramètres) dans le paramètre tools. Claude décide quand les appeler en fonction du contexte. Quand il décide d’utiliser un outil, il retourne un bloc tool_use avec les paramètres. Vous exécutez la fonction côté serveur, puis renvoyez le résultat via un message tool_result. Claude intègre le résultat et poursuit sa réponse.

Outils natifs disponibles en plus de vos outils personnalisés : web_search (recherche web temps réel), web_fetch (récupération de contenu web), code_execution (Python sandboxé), computer_use (contrôle d’interface graphique), bash (exécution de commandes), text_editor (édition de fichiers).

Le paramètre tool_choice contrôle le comportement : auto (Claude décide, par défaut), any (force l’utilisation d’un outil), tool (force un outil spécifique), none (désactive les outils).

Le programmatic tool calling (GA en 2026) permet à Claude d’écrire du code qui appelle vos outils dans un conteneur d’exécution, réduisant la latence des workflows multi-outils et la consommation de tokens.

Les outils MCP sont aussi supportés : convertissez les définitions inputSchema d’un serveur MCP vers le format Claude et passez-les dans le paramètre tools.

Extended Thinking via l’API

Extended Thinking donne à Claude un « budget de réflexion » en tokens avant de répondre. Activez-le avec le paramètre thinking :

{
  "model": "claude-opus-4-6",
  "max_tokens": 20000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 16000
  },
  "messages": [...]
}

Le budget_tokens détermine le maximum de tokens que Claude peut utiliser pour son raisonnement interne. Commencez à 1 024 et augmentez progressivement. Les tokens de thinking sont facturés au prix standard des tokens output.

Sur Opus 4.6, le paramètre effort (GA en mars 2026) remplace budget_tokens pour contrôler la profondeur de réflexion de manière plus intuitive. Le interleaved thinking est activé automatiquement sur Opus 4.6 avec adaptive thinking, permettant à Claude de réfléchir entre les appels d’outils.

Vision et support PDF

Tous les modèles Claude actuels supportent l’input d’images et de documents PDF. Les images sont envoyées en base64 avec leur media_type (JPEG, PNG, GIF, WebP). Les PDF sont envoyés comme type document en base64 avec media_type: "application/pdf".

Claude peut analyser des captures d’écran, des diagrammes, des photos de tableaux blancs, des maquettes d’interface, des graphiques de données et des pages de documents numérisés. La vision est particulièrement utile pour le prototypage d’interfaces (donner une capture d’écran et demander de la reproduire en code) et l’extraction de données depuis des documents PDF.

La Files API (en beta publique) simplifie le workflow : uploadez un fichier une fois, puis référencez-le dans plusieurs requêtes Messages sans le renvoyer à chaque appel.

Compaction API (beta)

Pour les conversations très longues, la Compaction API (beta sur Opus 4.6) fournit un résumé côté serveur du contexte accumulé, permettant des conversations effectivement infinies. Plutôt que de tronquer brutalement l’historique quand vous approchez de la limite de contexte, la compaction produit un résumé intelligent qui préserve les informations essentielles tout en libérant de l’espace pour de nouveaux échanges.

Streaming SSE

Ajoutez "stream": true à votre requête pour recevoir les tokens au fur et à mesure via Server-Sent Events (SSE). Indispensable pour les interfaces conversationnelles où la latence perçue compte.

Les SDKs Python et TypeScript offrent plusieurs façons de consommer le stream (sync/async). Le SDK PHP utilise createStream(). Les événements incluent content_block_start, content_block_delta (avec text_delta ou thinking_delta), content_block_stop, et message_stop.

Quand Extended Thinking est activé en streaming, les blocs de thinking arrivent via des événements thinking_delta, suivis d’un signature_delta pour la vérification d’intégrité. Si vous configurez thinking.display: "omitted", les deltas de thinking sont supprimés pour un streaming plus rapide, tout en préservant la signature pour la continuité multi-tour.

Batch Processing (50 % de remise)

Le Batch API traite vos requêtes en mode asynchrone avec livraison garantie sous 24 heures, en échange d’une remise de 50 % sur tous les tokens. Idéal pour la génération de contenu en masse, l’analyse de datasets, le traitement de documents non urgents et les rapports de fin de journée.

Le workflow : soumettez un batch de requêtes, pollez le statut, téléchargez les résultats par custom_id. La remise Batch se cumule avec le prompt caching, permettant des économies combinées allant jusqu’à 75 %.

Prompt Caching

Le prompt caching stocke un préfixe réutilisable de votre prompt pour ne pas le retraiter à chaque requête. Les lectures de cache coûtent environ 0,1× le prix de base, soit une réduction de 90 % sur les tokens répétés.

Deux durées de cache disponibles : 5 minutes (écriture à 1,25× le prix de base) et 1 heure (écriture à 2× le prix de base). La lecture de cache est identique dans les deux cas (0,1×).

Le caching est particulièrement efficace quand votre prompt système dépasse 1 024 tokens. Les tokens lus depuis le cache ne comptent pas dans votre ITPM (input tokens per minute), ce qui peut multiplier votre débit effectif par 5 à 10.

Pour les workflows Extended Thinking, privilégiez le cache 1 heure : les tâches de réflexion dépassent souvent 5 minutes, et vous risquez de perdre le cache entre les tours.

Plateformes disponibles

L’API Claude est accessible via trois plateformes, chacune avec ses avantages.

API directe Anthropic (api.anthropic.com) : accès en premier aux nouveaux modèles et fonctionnalités. Le choix par défaut pour la majorité des développeurs.

AWS Bedrock : intégration native dans l’écosystème AWS, facturation via votre compte AWS, endpoints régionaux pour la résidence des données (y compris EU). Idéal si vous êtes déjà dans AWS et avez des exigences de conformité.

Google Vertex AI : même logique pour l’écosystème Google Cloud. Endpoints globaux (routage dynamique) et régionaux (routage géographique garanti) disponibles depuis Sonnet 4.5+.

Anthropic propose aussi un endpoint compatible OpenAI SDK : changez votre clé API, l’URL de base et le nom du modèle dans vos intégrations OpenAI existantes pour tester Claude sans réécrire votre code. La compatibilité couvre les fonctionnalités de base du chat completions.

Sécurité et conformité

Quelques points essentiels pour les déploiements de production.

Ne jamais exposer la clé API côté client. Utilisez uniquement des appels serveur. Si vous construisez une application web, votre frontend doit passer par votre backend qui détient la clé.

Data residency. Le paramètre inference_geo permet de forcer l’inférence en US uniquement (surcoût 1,1× pour les modèles post-février 2026). Pour les déploiements européens avec contraintes strictes, AWS Bedrock et Vertex AI offrent des régions EU.

Zero Data Retention (ZDR). Disponible pour les clients Enterprise. Les prompts et réponses ne sont pas stockés côté Anthropic.

Admin API. 25 endpoints pour la gestion programmatique de l’organisation : rôles utilisateurs (6 niveaux), workspaces, clés API, monitoring d’usage (granularité jusqu’à 1 minute). Les rapports d’usage permettent de filtrer par modèle, workspace, clé API, tier de service et géographie.

Rate limits. Les limites (RPM, ITPM, OTPM) progressent avec vos tiers de dépenses. Les tokens lus depuis le cache ne comptent pas dans votre ITPM, ce qui multiplie le débit effectif.

Bonnes pratiques pour la production

Commencez par Sonnet, montez vers Opus si nécessaire. Sonnet 4.6 à 3 $/15 $ par MTok couvre 90 % des cas d’usage de production. Réservez Opus aux tâches où la qualité supplémentaire justifie le coût (5×).

Activez le prompt caching dès que votre system prompt dépasse 1 024 tokens. L’économie est immédiate (90 % sur les tokens répétés) et le gain de débit est considérable.

Utilisez le Batch API pour tout ce qui n’est pas temps réel. La remise de 50 % se cumule avec le caching pour des économies allant jusqu’à 75 %.

Implémentez des retries avec backoff exponentiel pour gérer les rate limits. Les SDKs officiels intègrent cette logique automatiquement.

Monitorez votre consommation. Utilisez les endpoints Usage et Cost de l’Admin API pour suivre la consommation par workspace, par clé et par modèle. Configurez des spend limits par workspace pour éviter les surprises.

Utilisez le streaming pour les interfaces conversationnelles. La latence perçue est significativement réduite quand l’utilisateur voit les tokens apparaître progressivement. Les SDKs requièrent le streaming quand max_tokens dépasse 21 333 pour éviter les timeouts HTTP.

Pour approfondir, consultez la documentation officielle de l’API Claude et le guide API IA pour débutants de Polydesk.