L'API Claude pour les développeurs

L'API Messages

L'API Messages est le point d'entrée HTTP central qui permet à n'importe quel programme de communiquer avec Claude. Plutôt que d'ouvrir une fenêtre de chat, votre code envoie une requête JSON structurée et reçoit une réponse JSON structurée. JSON (JavaScript Object Notation) est un format texte standard pour l'échange de données.

Chaque requête doit inclure trois éléments : l'identifiant du modèle (quelle version de Claude utiliser), max_tokens (le nombre maximum de tokens, ou fragments de mots, que Claude peut générer dans la réponse), et un tableau messages (l'historique de la conversation sous forme de paires rôle/contenu).

Le SDK Anthropic (kit de développement logiciel) officiel pour Node.js enveloppe cet appel HTTP dans une simple fonction JavaScript. Installez-le avec npm, puis écrivez quelques lignes :

• Définissez votre clé API comme variable d'environnement sous le nom ANTHROPIC_API_KEY.
• Créez un client : const Anthropic = require("@anthropic-ai/sdk"); const client = new Anthropic();
• Appelez client.messages.create({ ... }) avec votre modèle, max_tokens et vos messages.
• Lisez la réponse depuis response.content[0].text.

Les identifiants de modèles pour juin 2026 sont claude-opus-4-8 (le plus puissant), claude-sonnet-4-6 (équilibre) et claude-haiku-4-5 (le plus rapide). Commencez par Haiku pendant l'apprentissage : il est peu coûteux et instantané.

System, user, assistant via l'API

Chaque appel à l'API Claude est construit à partir d'une séquence de messages, chacun porte un rôle. Les trois rôles sont system, user et assistant. Le rôle system est un paramètre spécial de premier niveau (pas dans le tableau messages) qui définit des instructions persistantes pour toute la conversation. Pensez-y comme au briefing que vous donnez à Claude avant que la conversation commence.

Le tableau messages alterne ensuite entre user (le tour humain) et assistant (la réponse de Claude). Vous pouvez pré-remplir ce tableau avec des tours passés pour simuler une conversation multi-tours, ou injecter un début de tour assistant pour guider le tout premier mot de la réponse.

Pourquoi l'ordre des rôles est-il important ? Claude est entraîné à respecter la hiérarchie : les instructions system ont le poids le plus élevé, puis vient l'historique de la conversation. Si un message user contredit le system prompt, Claude suit le system prompt. Cela fait du paramètre system l'endroit idéal pour les règles, les personas, les formats de sortie et les garde-fous de sécurité.

• system : chaîne de caractères de premier niveau, définie une fois par requête, jamais affichée comme bulle de message.
• user : un tour humain, obligatoire au moins une fois en tant que dernier message.
• assistant : les réponses précédentes de Claude, ou une chaîne de pré-remplissage pour contraindre la prochaine réponse.
• Les messages doivent alterner user/assistant ; deux tours user consécutifs sont rejetés par l'API.

Utilisation des outils via l'API

L'API Claude vous permet de fournir au modèle une liste d'outils (aussi appelés définitions de fonctions) qu'il peut invoquer. Chaque outil est un objet JSON décrivant un nom, une description et un schéma d'entrée (un objet JSON Schema qui indique à Claude quels paramètres l'outil accepte). Claude n'exécute jamais l'outil lui-même ; il renvoie un bloc structuré tool_use que votre code doit traiter.

Un cycle typique fonctionne ainsi :

1. Vous envoyez une requête messages qui inclut un tableau tools.
2. Si Claude décide d'appeler un outil, le stop_reason de la réponse est "tool_use" et le contenu contient un bloc tool_use avec un id, le name de l'outil et l'objet input.
3. Votre code exécute l'action réelle (requête en base de données, appel API, calcul), puis ajoute un bloc tool_result à la conversation en utilisant le même tool_use_id.
4. Vous renvoyez la conversation mise à jour à Claude, qui lit le résultat et produit sa réponse finale.

Deux choix de conception clés affectent la fiabilité. Premièrement, rédigez la description de l'outil comme si vous expliquiez la fonction à un collègue débutant : Claude s'en sert pour décider si et quand appeler l'outil. Deuxièmement, rendez votre schéma d'entrée strict : marquez les champs obligatoires, utilisez enum quand les valeurs sont fixes, et évitez les champs string vagues quand un nombre ou un booléen est plus adapté. Des schémas vagues produisent des entrées vagues.

Quand vous souhaitez que Claude appelle exactement un outil précis, définissez tool_choice à {"type": "tool", "name": "your_tool_name"}. La valeur par défaut "auto" laisse Claude décider. Utilisez "any" pour forcer au moins un appel d'outil sans préciser lequel.

Réponses en streaming

Par défaut, l'API Anthropic attend que le modèle ait terminé de générer avant d'envoyer quoi que ce soit. Le streaming change cela : l'API envoie chaque token (un fragment de mot, environ 3 à 4 caractères) à votre client au moment où il est produit, de sorte que l'utilisateur voit le texte apparaître mot par mot au lieu d'attendre la réponse complète.

Le streaming utilise le protocole Server-Sent Events (SSE). Le serveur maintient la connexion HTTP ouverte et pousse de petits blocs d'événements. Chaque bloc contient un delta, c'est-à-dire le nouvel incrément de texte à ajouter. Votre client accumule les deltas pour reconstituer le message complet.

Pour activer le streaming avec le SDK Python ou Node d'Anthropic, passez stream=True (Python) ou utilisez la méthode .stream() (Node). Le SDK expose un itérateur asynchrone afin de traiter un bloc à la fois sans tout mettre en mémoire tampon. Cela compte pour les longues réponses : une réponse de 4000 tokens peut commencer à s'afficher en moins d'une seconde au lieu d'attendre plusieurs secondes.

• stream=True (Python) : retourne un gestionnaire de contexte ; itérez text_stream pour obtenir les fragments de texte bruts.
• .stream() (Node/TS) : retourne un itérable asynchrone ; utilisez for await pour consommer les blocs.
• Types d'événements : message_start, content_block_delta, message_delta, message_stop.
• Les statistiques d'utilisation arrivent dans le dernier événement message_stop, pas au début.

Mise en cache des prompts via l'API

Chaque appel API retraite l'intégralité des tokens envoyés. Le prompt caching vous permet de marquer les sections stables de votre requête afin qu'Anthropic stocke une version compilée sur ses serveurs. Les appels suivants qui atteignent le même préfixe évitent le retraitement et bénéficient d'un tarif bien plus bas : environ 10 % du coût d'entrée normal pour un cache hit, contre 125 % pour l'écriture initiale qui alimente le cache.

Vous marquez une limite mise en cache en ajoutant "cache_control": {"type": "breakpoint"} dans un bloc de contenu. Claude lit votre prompt de haut en bas et met en cache tout ce qui précède ce marqueur. Vous pouvez placer jusqu'à quatre points de rupture par requête. Le schéma le plus courant consiste à placer un point de rupture après un long prompt système ou un document volumineux réutilisé dans de nombreux appels.

Quelques règles déterminent si le cache est effectivement utilisé :

• Le préfixe doit comporter au moins 1024 tokens (environ 750 mots) pour être éligible à la mise en cache.
• Les entrées du cache expirent après cinq minutes d'inactivité ; chaque hit remet le compteur à zéro.
• Le modèle, la version et l'ensemble du contenu situé avant le point de rupture doivent être octet pour octet identiques entre les appels.
• Modèles pris en charge (juin 2026) : claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5.

La réponse de l'API inclut un objet usage avec les champs cache_creation_input_tokens et cache_read_input_tokens, ce qui vous permet de vérifier les hits et de mesurer les économies en temps réel.

L'API Batch

L'API Batch vous permet de soumettre jusqu'à 10 000 requêtes en un seul appel et de récupérer tous les résultats de manière asynchrone (c'est-à-dire que vous n'attendez pas de réponse en direct : vous revenez consulter les résultats plus tard). En échange de cette souplesse, Anthropic applique une remise de 50 % par token par rapport à l'API temps réel standard.

Vous envoyez un fichier JSON contenant une liste de requêtes, chacune dotée d'un custom_id unique afin de faire correspondre les résultats aux entrées. Claude les traite en arrière-plan, en quelques minutes en général pour des centaines de requêtes, bien que le SLA (Service Level Agreement, la garantie officielle de délai) autorise jusqu'à 24 heures.

L'API Batch possède sa propre limite de débit indépendante, séparée de l'API temps réel. Cela signifie qu'un travail batch intensif n'empiète pas sur votre quota interactif. Elle est idéale pour toute tâche hors ligne : génération de jeux de données, évaluations, traduction de grands catalogues ou classification de milliers d'enregistrements.

• Modèles supportés : claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5
• Nombre maximum de requêtes par batch : 10 000
• Remise : 50 % sur les tokens en entrée et en sortie par rapport au tarif temps réel
• Format des résultats : une ligne JSONL par requête, associée par custom_id
• Annulation : vous pouvez annuler un batch en cours d'exécution avec un seul appel API

Compter les tokens

Avant d'envoyer une requête à Claude, vous pouvez demander à l'API de compter exactement combien de tokens (les morceaux de texte que le modèle lit et écrit) cette requête consommera. On utilise pour cela le point de terminaison de comptage de tokens : POST /v1/messages/count_tokens. Il accepte le même corps qu'une requête de messages normale, mais ne renvoie qu'un comptage, jamais une réponse, et ne coûte rien.

Les comptes de tokens sont importants pour deux raisons. Premièrement, chaque modèle possède une fenêtre de contexte (le nombre maximum de tokens qu'il peut traiter en une seule fois) : 200 000 pour Opus et Sonnet, 200 000 pour Haiku. Deuxièmement, la facturation se fait par token en entrée et en sortie, donc envoyer trop de tokens est un gaspillage d'argent, et en envoyer trop peu risque de tronquer votre prompt. Le comptage vous permet de rester sous la limite et d'estimer le coût avant de valider.

Ce que vous pouvez compter avant d'envoyer :

• Le prompt système seul, pour en comprendre le coût fixe.
• Les définitions d'outils, qui surprennent souvent les développeurs par leur taille.
• L'historique de conversation, pour décider quand résumer ou supprimer les anciens tours.
• Les fichiers envoyés ou les longs documents, pour vérifier qu'ils tiennent dans la fenêtre.

Pour le budget de tokens, définissez un plafond souple dans votre code : si input_tokens retourné par le point de terminaison de comptage dépasse, par exemple, 150 000, tronquez ou résumez avant d'envoyer. Vous pouvez aussi combiner le comptage avec le paramètre max_tokens (qui limite la longueur de la sortie) pour contrôler précisément la dépense totale par appel.

Identifiants de modèle, tarification et migration

Chaque modèle Claude possède un identifiant de modèle, la chaîne exacte que vous passez à l'API pour demander une version spécifique. En juin 2026, les trois identifiants actuels sont claude-opus-4-8 (le plus capable, le plus coûteux), claude-sonnet-4-6 (équilibre entre performance et coût) et claude-haiku-4-5 (le plus rapide, le moins coûteux). Utilisez toujours l'identifiant complet avec numéro de version dans le code de production, jamais un alias comme "claude-opus" sans suffixe de version, car Anthropic peut silencieusement rediriger les alias vers des modèles plus récents et modifier vos coûts ou comportements.

Choisir le bon modèle est un arbitrage coût-performance. Une règle pratique :

• Opus (claude-opus-4-8) : décisions d'architecture, raisonnement complexe, analyse de longs documents, boucles agentiques où la qualité prime.
• Sonnet (claude-sonnet-4-6) : tâches de codage courantes, résumé, rédaction, workflows multi-étapes où vitesse et coût comptent.
• Haiku (claude-haiku-4-5) : classification, routage, recherches rapides, traitements par lots à fort volume où la latence est critique.

La migration consiste à remplacer un ancien identifiant de modèle par un plus récent dans votre base de code. La méthode sûre est la suivante : mettez à jour la chaîne d'identifiant, exécutez votre suite d'évaluation ou de tests existante sur le nouveau modèle, comparez les sorties sur un échantillon de vraies invites, puis déployez. Comme les modèles plus récents peuvent refuser différemment ou formater les sorties autrement, ne migrez jamais sans étape de comparaison. Anthropic publie un guide de migration pour chaque génération ; consultez-le pour identifier les changements cassants dans les formats d'appel d'outils ou les tailles de fenêtre de contexte avant de basculer.

La tarification est par token (un token correspond à environ quatre caractères de texte en anglais). Vous payez séparément les tokens d'entrée (ce que vous envoyez) et les tokens de sortie (ce que le modèle retourne). Les tokens de sortie coûtent plus cher. Utilisez le prompt caching pour réutiliser un grand prompt système entre les appels et réduire les coûts d'entrée jusqu'à 90 % sur la portion mise en cache. L'API Batch d'Anthropic offre 50 % de réduction sur les tokens d'entrée et de sortie, au prix d'une latence plus élevée, idéale pour la génération de jeux de données hors ligne.

Entrées vision et PDF

L'API Claude accepte bien plus que du texte. Vous pouvez envoyer des images et des fichiers PDF directement dans le tableau messages, en complément ou à la place d'un prompt textuel. Le modèle lit le contenu visuel et raisonne dessus exactement comme il le ferait avec des mots écrits. Cette capacité s'appelle l'entrée multimodale (multi-format, pas uniquement texte).

Les images sont transmises sous forme de chaînes encodées en base64 (une façon de représenter des données binaires sous forme de texte ASCII pur) dans un bloc content avec "type": "image". Vous précisez le type de média, par exemple image/jpeg, image/png, image/gif ou image/webp. Vous pouvez aussi passer une URL publique en utilisant "type": "image" avec une source "url" à la place du base64.

Les PDF utilisent "type": "document" avec "media_type": "application/pdf" et le contenu du fichier en base64. Claude lit la couche texte complète du PDF et, lorsque les pages contiennent des diagrammes ou des graphiques, il les interprète également visuellement. Les PDF sont limités à 100 pages et environ 32 Mo par fichier.

• Formats d'image acceptés : JPEG, PNG, GIF, WebP.
• Taille maximale par image par requête : 20 Mo (le poids encodé en base64 est environ 33 % supérieur au fichier brut).
• Jusqu'à 20 images par requête sur les modèles actuels.
• PDF : 100 pages maximum, 32 Mo brut. Contenu textuel et visuel analysés.
• La vision est disponible sur claude-opus-4-8, claude-sonnet-4-6 et claude-haiku-4-5.