Accueil / L'API Claude pour ceux qui construisent

La requête, une seule porte d'entrée

Toute interaction avec Claude passe par un seul point d'entrée HTTP, la requête POST /v1/messages, qui reçoit un tableau de tours et rend toujours la même structure de réponse.

L'API Claude ne compte qu'une seule porte d'entrée : la requête POST /v1/messages, appelée l'API Messages. Chaque échange, qu'il tienne en un seul tour ou qu'il enchaîne une longue conversation, passe par ce même point d'entrée, avec un corps qui porte un tableau messages et un modèle choisi. Un client HTTP ordinaire suffit : aucune autre route à mémoriser, quel que soit le modèle interrogé ou la nature de la demande.

Un champ obligatoire, sans valeur par défaut

Le corps de la requête porte un champ nommé exactement max_tokens, qui fixe le nombre maximal de jetons que le modèle peut générer avant de s'arrêter. Ce champ n'a pas de valeur par défaut : il est obligatoire sur chaque requête, au même titre que le modèle et le tableau messages. Ce champ conditionne aussi le coût et la durée de la génération, sans pour autant l'imposer : le modèle peut très bien s'arrêter avant d'atteindre cette limite, dès qu'il juge sa réponse achevée. Un cas particulier existe : envoyer max_tokens à 0 ne demande aucune génération, seulement le pré remplissage du cache de prompt en vue d'une requête suivante.

// Corps minimal d'une requête à l'API Messages
{
  "model": "claude-sonnet-5",
  "max_tokens": 300,
  "messages": [
    { "role": "user", "content": "Résume ce texte en une phrase." }
  ]
}

Une réponse toujours structurée de la même façon

La réponse rendue par l'API suit toujours la même forme, quel que soit le modèle interrogé. Le champ content porte un tableau de blocs, le champ model confirme le modèle réellement utilisé, et le champ stop_reason indique pourquoi la génération s'est arrêtée : end_turn pour une réponse achevée naturellement, max_tokens pour une coupure sur la limite fixée, stop_sequence pour une séquence d'arrêt rencontrée, et selon le contexte de la requête, tool_use, refusal, pause_turn ou model_context_window_exceeded. Quand une séquence d'arrêt a déclenché la coupure, elle est répétée dans le champ stop_sequence.

Le champ usage ferme la réponse avec quatre compteurs : input_tokens, output_tokens, cache_creation_input_tokens et cache_read_input_tokens. Ces quatre nombres suffisent à calculer le coût exact d'un échange sans consulter aucune autre source, et ils reviennent sur chaque requête, même la plus simple. Lire input_tokens avant d'envoyer le tour suivant permet aussi de savoir combien de marge reste disponible dans la conversation en cours.

Cette même structure de réponse revient dans la déclaration d'un outil, où le champ stop_reason prend la valeur tool_use pour signaler une demande d'usage plutôt qu'une réponse achevée.