Documentation de l'API Anthropic Messages : points d'accès, requêtes, vision et backends d'agents

L’API Anthropic Messages est l’interface HTTP principale pour envoyer des prompts à Claude. Le point d’accès central est POST /v1/messages : vous fournissez un modèle, une liste de blocs de contenu typés, et une limite de tokens, puis recevez un message assistant contenant un ou plusieurs blocs de sortie.

Ce guide transforme la documentation de l’API Anthropic en une checklist d’implémentation. Il couvre le contrat de requête, l’état multi-tours, le streaming, la vision, l’API Files, l’utilisation d’outils et les choix nécessaires lorsqu’un backend d’agent doit prendre en charge à la fois des fournisseurs de modèles natifs Anthropic et compatibles OpenAI.

Point d’accès de l’API Messages et en-têtes requis

L’API Messages native d’Anthropic utilise ce point d’accès :

POST https://api.anthropic.com/v1/messages

Les requêtes HTTP directes incluent généralement ces en-têtes :

En-tête	Objectif
x-api-key	Authentifie le compte Anthropic
anthropic-version	Sélectionne la version documentée du contrat d’API
content-type: application/json	Déclare un corps de requête JSON

L’en-tête de version de l’API n’est pas une version de modèle. Il contrôle le comportement de l’API HTTP, tandis que le champ model sélectionne le modèle Claude utilisé pour l’inférence. Conservez les deux valeurs dans la configuration plutôt que de les disperser dans le code applicatif.

Structure de la requête et de la réponse

Une requête de base contient trois champs :

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Expliquez les clés d'idempotence en deux paragraphes."
    }
  ]
}

La réponse est un message assistant plutôt qu’une chaîne brute. Sa propriété content est un tableau de blocs typés, donc le code de production doit inspecter le type de chaque bloc avant de lire ses champs.

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Une clé d'idempotence..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 126
  }
}

Cette conception basée sur les blocs devient importante une fois que vous ajoutez des images ou des outils. Un seul tour assistant peut contenir du texte et une demande d’outil, et un tour utilisateur peut contenir du texte ainsi que des blocs d’image ou de document.

Une requête curl minimale

Stockez les identifiants dans une variable d’environnement et utilisez un ID de modèle actuellement disponible pour votre compte Anthropic :

export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="your-claude-model-id"

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": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "Donnez trois façons pratiques de réduire la latence d'une API."
      }
    ]
  }'

Ne codez pas en dur un nom de modèle copié d’un ancien tutoriel. La disponibilité et les alias des modèles peuvent changer : la configuration de déploiement doit donc utiliser un ID de modèle vérifié dans la documentation actuelle du fournisseur ou dans sa console.

Utilisation en Python avec le SDK Anthropic

Le SDK Python officiel gère les en-têtes d’authentification et convertit la réponse en objets typés :

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": "Écrivez une fonction Python qui valide une chaîne UUID.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Itérer sur les blocs de contenu est plus sûr que de supposer que message.content[0] est toujours du texte. Les applications d’agents peuvent recevoir des blocs d’utilisation d’outils, et les fonctionnalités multimodales peuvent ajouter d’autres types de blocs à la conversation.

Conversations multi-tours et prompts système

L’API Messages est sans état. Votre application renvoie l’historique de conversation pertinent avec chaque requête :

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 512,
  "system": "Vous êtes un assistant concis pour la documentation d'API.",
  "messages": [
    {"role": "user", "content": "Que signifie HTTP 429 ?"},
    {"role": "assistant", "content": "Cela indique une limitation de débit."},
    {"role": "user", "content": "Comment mon client doit-il réessayer ?"}
  ]
}

Anthropic place l’instruction système dans le champ system de premier niveau plutôt que dans un message avec role: "system". C’est l’une des différences importantes à prendre en compte lors de la traduction des requêtes depuis les schémas compatibles OpenAI.

Pour les sessions longues, ne renvoyez pas une transcription illimitée. Conservez les derniers tours, préservez les décisions et les résultats d’outils qui affectent encore la tâche, et résumez le contexte plus ancien avant que le prompt n’atteigne la limite de contexte du modèle sélectionné.

Réponses en streaming

Définissez stream: true lorsque l’interface doit afficher la sortie de manière incrémentielle :

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with client.messages.stream(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Expliquez le pooling de connexions de base de données."}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Le streaming améliore la latence perçue, mais ajoute du travail de gestion d’état. Votre application doit gérer une connexion qui se ferme prématurément, du texte partiel, l’ordre des événements et les métadonnées d’utilisation finales. Pour les agents utilisant des outils, mettez en mémoire tampon le bloc complet d’entrée d’outil avant de l’analyser ou de l’exécuter.

Requêtes de l’API Claude Vision

L’API Claude Vision utilise le même point d’accès Messages. Ajoutez un bloc de contenu d’image avant la question textuelle associée. Les images peuvent être fournies sous forme de données base64 prises en charge ou via un type de source autorisé décrit dans la documentation actuelle sur la vision.

import base64
import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with open("architecture.png", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode("utf-8")

message = client.messages.create(
    model=os.environ["ANTHROPIC_VISION_MODEL"],
    max_tokens=700,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Identifiez deux risques de fiabilité dans ce diagramme d'architecture.",
                },
            ],
        }
    ],
)

Redimensionnez les images surdimensionnées avant de les envoyer. Les grandes images augmentent le temps de transfert et l’utilisation de tokens sans nécessairement améliorer la réponse. Validez également le type MIME ; déclarer des données JPEG comme PNG est une cause fréquente de rejet des requêtes.

Utilisation de l’API Files d’Anthropic

L’API Files d’Anthropic est utile lorsqu’un fichier doit être téléchargé une fois et référencé par des appels ultérieurs à l’API Messages, au lieu d’être encodé et transmis à plusieurs reprises. La disponibilité exacte, les types de fichiers pris en charge et les champs de requête peuvent différer selon l’état de la fonctionnalité : vérifiez donc la documentation actuelle de l’API Files avant de vous y fier en production.

Une intégration typique comporte deux étapes :

1. Téléchargez le fichier et persistez l’identifiant de fichier retourné avec l’enregistrement de document de votre application.
2. Référencez cet identifiant dans un bloc de contenu pris en charge lors de la création d’un message.

Traitez les ID de fichiers comme des ressources spécifiques au fournisseur. Enregistrez quel fournisseur et quel compte a créé chaque ID, appliquez vos propres contrôles d’accès et définissez une politique de suppression. Un identifiant de fichier ne doit pas être accepté directement d’un utilisateur non fiable sans vérifications d’autorisation.

Pour les petites images occasionnelles, le base64 est simple. Pour les documents utilisés dans de nombreuses requêtes, une ressource de fichier fournisseur peut réduire les téléchargements répétés. Si votre application doit fonctionner avec plusieurs fournisseurs, conservez l’objet original dans votre propre stockage et créez des ID de fichiers spécifiques au fournisseur comme un cache.

Utilisation d’outils pour les backends d’agents

Les outils permettent à Claude de demander une fonction définie par l’application. Votre backend décrit chaque outil avec un nom, un objectif et un contrat d’entrée au format JSON Schema. Le modèle peut alors renvoyer un bloc tool_use plutôt que de faire semblant d’avoir exécuté l’opération.

{
  "name": "get_order_status",
  "description": "Rechercher le statut actuel d'une commande client.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "L'identifiant de commande affiché au client."
      }
    },
    "required": ["order_id"]
  }
}

La boucle d’exécution sécurisée est la suivante :

1. Envoyez les messages et les définitions d’outils au modèle.
2. Détectez un bloc de contenu tool_use.
3. Validez son entrée par rapport au schéma et à vos règles d’autorisation.
4. Exécutez l’outil dans un environnement contrôlé.
5. Renvoyez un bloc tool_result correspondant dans le tour utilisateur suivant.
6. Continuez jusqu’à ce que le modèle produise une réponse normale ou atteigne votre limite de boucle.

N’exécutez jamais les arguments d’outil comme des commandes shell, SQL ou des chemins de fichiers de confiance. Pour les agents de codage, exécutez les commandes générées dans un environnement isolé comme Novita Agent Sandbox, avec des limites explicites de temps, réseau, système de fichiers et ressources.

Requêtes natives Anthropic vs compatibles OpenAI

Les API natives Anthropic et compatibles OpenAI résolvent le même problème général, mais leurs formats filaires ne sont pas identiques.

Aspect	API Anthropic Messages	API chat compatible OpenAI
Point d’accès courant	/v1/messages	/v1/chat/completions
Instruction système	Champ system de premier niveau	Généralement un message system ou developer
Représentation de la sortie	Blocs de contenu typés	Généralement choices[].message
Demande d’outil	Bloc tool_use	Généralement tool_calls
Résultat d’outil	Bloc de contenu tool_result	Généralement un message de rôle tool

Un point d’accès compatible OpenAI est précieux lorsque votre application utilise déjà le SDK OpenAI ou doit passer d’un modèle à un autre avec des modifications minimales du transport. Novita AI expose une API LLM compatible OpenAI, de sorte que la même structure client peut cibler plusieurs modèles disponibles en modifiant l’URL de base et la configuration du modèle.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/v3/openai",
)

response = client.chat.completions.create(
    model=os.environ["NOVITA_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "Examinez cette stratégie de réessai pour les modes de défaillance.",
        }
    ],
)

print(response.choices[0].message.content)

Ce n’est pas une traduction directe de chaque fonctionnalité d’Anthropic. Si votre application dépend de blocs de contenu spécifiques à Anthropic, de la sémantique des outils, des citations ou des fonctionnalités bêta, conservez un adaptateur natif Anthropic. Utilisez le chemin partagé compatible OpenAI pour les charges de travail qui correspondent à son modèle de requête courant.

Construire un backend d’agent neutre vis-à-vis du fournisseur

Un backend neutre vis-à-vis du fournisseur doit normaliser les concepts applicatifs sans prétendre que tous les fournisseurs sont identiques. Une conception pratique comporte quatre couches :

1. Modèle de conversation : stockez les rôles, le texte, les images, les appels d’outils et les résultats d’outils dans un schéma interne.
2. Adaptateur fournisseur : traduisez le schéma interne en charges utiles Anthropic Messages ou compatibles OpenAI.
3. Registre de capacités : suivez si le modèle sélectionné prend en charge la vision, les outils, la sortie structurée ou tout autre comportement requis.
4. Couche d’exécution : exécutez les outils et le code séparément du fournisseur d’inférence.

Cette séparation permet à une équipe d’utiliser Claude là où le comportement natif d’Anthropic est important, tout en routant les charges de travail compatibles vers un modèle open source via Novita AI. Le chemin open source peut être utile pour le contrôle des coûts, l’expérimentation de modèles, les exigences de localisation des données ou pour éviter une dépendance à un seul fournisseur. Testez la qualité des sorties et la fiabilité des outils sur vos propres tâches plutôt que de supposer que deux modèles sont interchangeables parce qu’ils acceptent tous deux des messages de chat.

Pour les charges de travail d’agents, la couche d’exécution mérite une attention particulière. Le changement de modèle ne protège pas votre infrastructure des commandes dangereuses. Utilisez un bac à sable isolé, imposez des listes d’autorisation d’outils, limitez les itérations et enregistrez chaque décision du modèle et résultat d’outil en supprimant les secrets.

Erreurs courantes et débogage

400 Bad Request

Vérifiez la forme JSON, les types de blocs de contenu, les champs obligatoires et si le modèle sélectionné prend en charge la fonctionnalité demandée. Enregistrez l’ID de requête du fournisseur et le corps d’erreur structuré, mais masquez les identifiants et les données de fichiers base64.

401 Authentication Error

Confirmez que la clé API est présente dans l’environnement d’exécution et appartient au fournisseur prévu. Anthropic utilise x-api-key pour les requêtes HTTP directes ; un client compatible OpenAI envoie généralement un jeton bearer automatiquement.

404 Model or Resource Not Found

Vérifiez l’ID du modèle par rapport à la documentation actuelle du fournisseur ou à sa console. Pour les ressources de l’API Files, vérifiez également que le fichier appartient au même compte et au même environnement que ceux utilisés par la requête.

429 Rate Limit

Réessayez avec un backoff exponentiel et du jitter, mais limitez le nombre de tentatives. Mettez en file d’attente les travaux en arrière-plan, limitez la concurrence par fournisseur et évitez de réessayer immédiatement chaque requête échouée au même intervalle.

Erreurs de limite de contexte ou de tokens

Réduisez l’historique de conversation, la taille des images, le contenu des fichiers ou la longueur de sortie demandée. Comptez l’ensemble de la requête, y compris les instructions système, les schémas d’outils, les résultats d’outils antérieurs et le contenu multimodal.

Articles recommandés

• Que sont les agents de codage ? Architecture, outils et boucles d’exécution
• Qu’est-ce que MCP ? Guide du développeur sur le Model Context Protocol
• Guide des LLM open source 2026 : modèles, compromis et déploiement

Checklist d’implémentation

• Conservez les clés API, les ID de modèles, les URL de base et les versions d’API dans la configuration d’exécution.
• Analysez les blocs de contenu typés au lieu de supposer une seule chaîne de texte.
• Stockez suffisamment d’état de conversation pour reconstruire chaque requête sans état.
• Validez les entrées d’outils et exécutez-les en dehors du processus du modèle.
• Ajoutez des timeouts, des limites de réessai, des ID de requête et une observabilité avec masquage.
• Conditionnez le routage des fournisseurs par capacité du modèle, pas seulement par prix ou nom.
• Revérifiez les ID de modèles, l’état des fonctionnalités, les limites et les tarifs avant le déploiement.

L’API Messages est simple au niveau HTTP. Le travail d’ingénierie le plus difficile apparaît lorsqu’une application ajoute du streaming, des entrées multimodales, des outils, des fichiers persistants ou plusieurs fournisseurs de modèles. Gardez ces préoccupations derrière des adaptateurs explicites, et votre backend d’agent pourra évoluer sans lier la logique métier à un seul format de requête.

FAQ

Quel est le point d’accès de l’API Anthropic Messages ?

Le point d’accès natif est POST https://api.anthropic.com/v1/messages. Les requêtes nécessitent une authentification, un en-tête de version d’API Anthropic, un ID de modèle, une limite de tokens et un tableau de messages.

L’API Anthropic Messages est-elle compatible OpenAI ?

Non. Les concepts se chevauchent, mais les prompts système, les blocs de contenu, les objets de réponse et les messages d’utilisation d’outils diffèrent. Utilisez un adaptateur fournisseur si une application doit prendre en charge les deux formats.

L’API Claude Vision utilise-t-elle un point d’accès séparé ?

Non. Les requêtes Vision utilisent l’API Messages avec des blocs de contenu d’image et de texte. Le modèle Claude sélectionné doit prendre en charge l’entrée d’images.

Quand dois-je utiliser l’API Files d’Anthropic ?

Utilisez-la lorsque des fichiers pris en charge doivent être référencés entre les requêtes et que des téléchargements base64 répétés seraient inefficaces. Conservez votre propre fichier source et enregistrement d’autorisation, car les ID de fichiers fournisseur sont des ressources spécifiques au compte.

Claude Code peut-il utiliser un backend d’API personnalisé ?

L’intégration de Claude Code dépend de l’authentification et de la configuration du fournisseur prises en charge par la version actuelle de Claude Code. Ne supposez pas qu’un point d’accès compatible OpenAI implémente l’API Messages d’Anthropic. Pour un agent personnalisé, un adaptateur neutre vis-à-vis du fournisseur est généralement plus clair que de tenter de rendre différents protocoles identiques.

Quand dois-je choisir un modèle open source via Novita AI ?

Considérez cette option lorsque vous souhaitez un changement de modèle compatible OpenAI, une expérimentation avec des modèles ouverts, ou un deuxième fournisseur pour des charges de travail compatibles. Conservez les requêtes natives Anthropic pour les fonctionnalités nécessitant un comportement d’API spécifique à Claude, et évaluez les deux chemins sur vos propres prompts et outils.