Votre première requête expliquée
Une explication ligne par ligne d’un appel Messages : le rôle de chaque champ et les données renvoyées.
Le guide de démarrage rapide vous permet d’obtenir une réponse. Cette page explique le rôle de chaque élément, afin que vous puissiez écrire vous-même la requête suivante.
La requête
curl https://aiprimetech.io/v1/messages \
-H "x-api-key: $CLAUDEAPIKEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello"}]
}'| Champ | Obligatoire | Son rôle |
|---|---|---|
model | oui | Le modèle à exécuter. Doit correspondre à un identifiant provenant de /v1/models à l’identique. |
max_tokens | oui | Limite stricte de la sortie. Le modèle s’arrête à cette limite, même au milieu d’une phrase. C’est un moyen de maîtriser les coûts, pas un objectif à atteindre. |
messages | oui | La conversation jusqu’ici, du plus ancien au plus récent. Chaque entrée comporte un role (user ou assistant) et content. |
system | non | Instructions qui s’appliquent à toute la conversation. Il s’agit d’un champ de premier niveau, et non d’un message avec role: system. |
temperature | non | 0–1. Une valeur plus faible rend le résultat plus déterministe. Ne définissez pas ce paramètre sans raison particulière. |
stream | non | true renvoie des événements envoyés par le serveur au lieu d’un seul corps JSON. Consultez Diffusion en continu. |
La réponse
{
"id": "msg_01ABC...",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [{"type": "text", "text": "Hello! How can I help?"}],
"stop_reason": "end_turn",
"usage": {"input_tokens": 9, "output_tokens": 12}
}contentest un tableau, et non une chaîne de caractères. Le texte se trouve danscontent[0].text. Le traiter comme une chaîne de caractères est l’erreur la plus courante côté client.stop_reasonindique pourquoi la génération s’est arrêtée :end_turn(terminée),max_tokens(limite atteinte — la réponse est tronquée),stop_sequence, outool_use.usagesert de base à votre facturation. Consignez-le dans les journaux ; c’est la seule base fiable pour l’attribution des coûts.
Si
stop_reason est max_tokens, votre réponse a été coupée. Augmentez max_tokens ou demandez une réponse plus courte — ne réessayez pas aveuglément, car la sortie tronquée vous est également facturée.Conversations à plusieurs tours
L’API est sans état. Pour poursuivre une conversation, vous renvoyez tout l’historique, y compris les réponses précédentes du modèle :
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "What is the capital of France?"},
{"role": "assistant", "content": "Paris."},
{"role": "user", "content": "And its population?"}
]
}Comme l’historique est renvoyé à chaque tour, le nombre de tokens d’entrée augmente avec la conversation, tout comme la facture. C’est pourquoi les longues sessions d’agent deviennent coûteuses. Mise en cache des prompts et gestion du contexte s’attaquent tous deux directement à ce problème.