Intégrer la Messages API : streaming, tool use, vision et coûts
Ce module couvre l'utilisation pratique de la Messages API d'Anthropic : structure des requêtes, streaming, appel d'outils, entrée d'images, et gestion des tokens et des coûts.
À retenir
- •Toute interaction avec Claude via l'API passe par un point d'entrée unique, la Messages API, qui accepte des messages avec un rôle utilisateur ou assistant.
- •Le champ stop_reason de la réponse indique pourquoi le modèle s'est arrêté de générer, par exemple end_turn, max_tokens ou tool_use.
- •Le tool use permet à Claude d'appeler des fonctions définies par le développeur en renvoyant un bloc structure que l'application doit exécuter puis retourner sous forme de résultat.
- •Le mode streaming renvoie la réponse progressivement et evite les delais d'attente sur les réponses longues.
- •Le prompt caching et la Batch API sont deux leviers directs pour réduire le coût d'utilisation de l'API à volume élevé.
La Messages API en pratique
L'ensemble des interactions programmatiques avec Claude passe par un point d'entrée unique, la Messages API. Une requête comprend au minimum un modèle cible, un nombre maximal de tokens de sortie et une liste de messages, chacun associé à un rôle, utilisateur ou assistant. La réponse renvoyée contient un ou plusieurs blocs de contenu, généralement du texte, mais potentiellement d'autres types de blocs selon les fonctionnalités activées, comme des blocs de raisonnement ou des appels d'outils.
La conversation est geree de manière sans état côté serveur : c'est à l'application d'envoyer à chaque nouvelle requête l'historique complet des messages pertinents pour que le modèle dispose du contexte nécessaire. Cette conception simple permet une grande flexibilité, par exemple pour resumer ou filtrer l'historique avant de le renvoyer, mais impose de gérer soi-même la persistance de la conversation.
Streaming pour les réponses longues
Par defaut, une requête à l'API attend que la réponse complète soit generee avant de la renvoyer, ce qui peut prendre du temps pour des réponses longues et risque de déclencher des delais d'attente côté client ou côté infrastructure réseau. Le mode streaming résout ce problème en renvoyant la réponse progressivement, événement par événement, au fur et à mesure que le modèle genere du texte.
Le streaming est recommandé des que la réponse attendue peut etre longue, ou pour toute interface utilisateur ou l'on souhaite afficher le texte au fur et à mesure qu'il est produit, comme dans un assistant conversationnel. Il est également utile pour observer en temps reel les appels d'outils demandes par le modèle dans une boucle agentique.
Tool use : donner des capacités à Claude
Le tool use, aussi appele function calling, permet de decrire à Claude un ensemble d'outils disponibles, chacun avec un nom, une description et un schéma des paramètres attendus. Lorsque le modèle juge qu'un outil est nécessaire pour répondre à la demande, il retourne un bloc de type tool_use contenant le nom de l'outil et les paramètres à utiliser, et le champ stop_reason de la réponse prend la valeur tool_use.
C'est alors à l'application d'exécuter reellement cet outil, par exemple interroger une base de données ou appeler une API externe, puis de renvoyer le résultat au modèle sous la forme d'un bloc tool_result dans un nouveau message utilisateur. Le modèle peut alors poursuivre la conversation en tenant compte de ce résultat, ou demander l'appel d'un autre outil. Cette boucle requête, execution, résultat, nouvelle requête constitue la base de la plupart des agents construits avec l'API Claude. Plusieurs appels d'outils peuvent etre demandes en parallele dans une seule réponse et doivent etre exécutés puis retournés ensemble.
Entrée d'images et contenu multimodal
La Messages API accepte des blocs de contenu de type image en plus du texte, avec une source fournie soit en base64, soit sous forme d'URL publique. Ce mécanisme permet de construire des applications qui mélangent texte et image dans une même requête, par exemple pour demander à Claude de decrire une capture d'ecran, d'extraire des informations d'un graphique, ou de comparer plusieurs images entre elles.
Le traitement d'une image consomme un nombre de tokens qui dépend de sa résolution, ce qui doit etre pris en compte dans l'estimation du coût d'une requête lorsque des images volumineuses sont envoyees régulièrement.
Gestion des tokens et optimisation des coûts
Le coût d'une requête à l'API Claude dépend du nombre de tokens en entrée et en sortie, avec des tarifs généralement différents pour chaque sens et selon le modèle choisi. Un token represente une unite de texte, approximativement une portion de mot, et non un caractère ou un mot entier. Avant d'envoyer une requête coûteuse en volume, il est possible d'estimer le nombre de tokens d'un prompt via un point d'entrée dédié de comptage de tokens.
Deux leviers principaux permettent de réduire les coûts à l'échelle. Le prompt caching permet de mettre en cache une partie stable et repetee du prompt, comme un system prompt long ou la description des outils, pour eviter de la refacturer integralement à chaque requête. La Batch API permet de soumettre un grand nombre de requêtes non urgentes pour un traitement asynchrone à coût réduit par rapport à des appels synchrones equivalents, un choix pertinent pour des tâches comme la classification en masse de documents qui n'exigent pas une réponse immediate.