Skip to main content
POST
Utilisez POST /v1/messages pour envoyer des requêtes à Claude au format Anthropic Messages. Les exemples configurent le SDK Anthropic officiel avec l’URL de base CometAPI et lisent votre clé API depuis $COMETAPI_KEY.
Pour les définitions des champs et les options propres aux modèles, consultez la documentation officielle Référence de l’API Messages. Pour les requêtes compatibles avec OpenAI, consultez Chat Completions.
Authentifiez-vous avec x-api-key ou Authorization: Bearer. Le SDK Anthropic utilise x-api-key. Les exemples HTTP incluent anthropic-version: 2023-06-01.

Démarrage rapide

Les exemples suivants demandent trois requêtes de recherche. Définissez $COMETAPI_KEY avant de les exécuter. Installez anthropic pour Python ou @anthropic-ai/sdk pour JavaScript :
La réponse contient un tableau content. Lisez les blocs dont type est text ; des blocs de réflexion et d’outils peuvent apparaître avant le texte.

Contrôler le raisonnement adaptatif

Définissez thinking.type sur adaptive et choisissez une valeur pour output_config.effort. L’exemple suivant utilise xhigh et lit le message terminé à partir d’un flux :
Le raisonnement contribue à la limite de sortie max_tokens. Prévoyez également de la place pour la réponse finale ainsi que pour le raisonnement. réponse sans bloc de raisonnement visible. Une réponse peut contenir du texte sans bloc de raisonnement visible. Conservez tous les blocs de raisonnement renvoyés sans les modifier dans l’historique de la conversation . Pour la configuration de raisonnement propre au modèle, consultez Réflexion. Les exemples omettent temperature, top_p et top_k ; consultez la documentation des paramètres du modèle sélectionné avant d’ajouter des contrôles d’échantillonnage.

Mettre les prompts en cache

Placez un point d’arrêt de cache sur le contenu de référence que vous réutilisez entre les requêtes. Enregistrez votre contenu de référence dans un fichier reference.txt encodé en UTF-8 avant d’exécuter cet exemple. Utilisez un préfixe qui respecte la longueur minimale pouvant être mise en cache:
Exécutez à nouveau la requête avec le même modèle, le même texte de référence et les mêmes paramètres de raisonnement. Examinez les compteurs d’utilisation pour déterminer si la requête a réutilisé un préfixe :
  • cache_creation_input_tokens compte les tokens écrits dans le cache.
  • cache_read_input_tokens compte les tokens lus depuis le cache.
  • input_tokens compte les données d’entrée traitées en dehors de ces compteurs de cache.
Lors de requêtes répétées, cache_read_input_tokens indique combien de tokens d’entrée ont été lus depuis le cache. L’exemple OpenAPI Prompt Cache contient une référence fictive complète que vous pouvez enregistrer sous reference.txt afin d’essayer l’exemple.

Diffuser les réponses en Streaming

Définissez stream: true pour les événements envoyés par le serveur. Le SDK expose les fragments de texte à mesure qu’ils arrivent :
Un flux de messages contient message_start, des événements de blocs de contenu, message_delta, et message_stop. Les blocs de contenu peuvent contenir du texte, de la réflexion ou de l’activité d’outil. Pour un bloc de texte, content_block_delta contient un text_delta. Lisez l’utilisation finale et le motif d’arrêt dans message_delta.

Contrôler l’effort

Définissez output_config.effort afin d’orienter la quantité de raisonnement. Cet exemple utilise low pour une courte explication et attend la fin du message diffusé en Streaming :
Utilisez la référence officielle sur l’effort pour choisir un niveau d’effort. Définissez séparément max_tokens afin de limiter la longueur de sortie.

Utiliser les outils serveur

Les outils serveur s’exécutent pendant la requête API et renvoient des blocs de résultats en même temps que la réponse de Claude.
Récupérez un article et demandez à Claude d’utiliser le document récupéré dans sa réponse. Cet exemple diffuse la réponse en continu et examine à la fois le texte final et le web_fetch_tool_result bloc :
La réponse associe un bloc server_tool_use à un web_fetch_tool_result contenant le document récupéré ou une erreur d’outil.

Renvoyer les résultats des outils client

Pour un outil client, Claude renvoie un bloc tool_use. Exécutez la fonction de votre application et envoyez son résultat dans un bloc tool_result avec le tool_use_id correspondant. Conservez l’intégralité du contenu de l’assistant entre les deux requêtes. Cet exemple fournit un résultat de commande fictif et demande à Claude d’utiliser ce résultat :

Exemple de réponse

Une requête non-Streaming renvoie un objet message. L’exemple suivant montre ses champs text et usage avec un identifiant de message illustratif :
La raison d’arrêt décrit l’action suivante. end_turn termine la réponse, max_tokens signifie que la sortie a atteint la limite, et tool_use demande le résultat d’un outil client résultat. Pour un tour d’outil serveur qui renvoie pause_turn, poursuivez avec le contenu de l’assistant renvoyé sans le modifier.

Autorisations

x-api-key
string
header
requis

Your CometAPI key passed via the x-api-key header. Authorization: Bearer $COMETAPI_KEY is also supported.

En-têtes

anthropic-version
string
défaut:2023-06-01

The Anthropic API version to use. Defaults to 2023-06-01.

Exemple:

"2023-06-01"

anthropic-beta
string

Comma-separated feature identifiers required by a specific beta API feature. Omit this header for the examples on this page.

Corps

application/json
model
string
défaut:claude-opus-5
requis

The Claude model to use. See the Models page for available Claude model IDs.

Exemple:

"claude-opus-5"

messages
object[]
requis

Conversation history. Use user and assistant messages with text strings or content-block arrays. Return complete assistant content blocks when continuing a tool call.

max_tokens
integer
requis

The maximum number of tokens to generate. The model may stop before reaching this limit. When using thinking, the thinking tokens count towards this limit.

Plage requise: x >= 1
Exemple:

1024

system

System prompt providing context and instructions to Claude. Can be a plain string or an array of content blocks (useful for prompt caching).

temperature
number

Sampling temperature. The examples omit sampling overrides.

Plage requise: 0 <= x <= 1
top_p
number

Nucleus sampling threshold. The examples omit sampling overrides.

Plage requise: 0 <= x <= 1
top_k
integer

Limits sampling to the k most likely tokens. The examples omit sampling overrides.

Plage requise: x >= 0
stream
boolean
défaut:false

If true, stream the response incrementally using Server-Sent Events (SSE). Events include message_start, content_block_start, content_block_delta, content_block_stop, message_delta, and message_stop.

stop_sequences
string[]

Custom strings that cause the model to stop generating when encountered. The stop sequence is not included in the response.

thinking
object

Thinking configuration. The adaptive example uses type adaptive and sets output_config.effort separately.

tools
object[]

Client tools define a name and input_schema. Server tools use a versioned type and name, such as the web_fetch and web_search examples on this page.

tool_choice
object

Controls how the model uses tools.

metadata
object

Request metadata for tracking and analytics.

output_config
object

Configuration for reasoning effort and structured output.

service_tier
enum<string>

The service tier to use. auto tries priority capacity first, standard_only uses only standard capacity.

Options disponibles:
auto,
standard_only

Réponse

Successful response. When stream is true, the response is a stream of SSE events.

id
string

Message identifier returned by the API.

type
enum<string>

Always message.

Options disponibles:
message
role
enum<string>

Always assistant.

Options disponibles:
assistant
content
object[]

The response content blocks. May include text, thinking, tool_use, and other block types.

model
string

Model ID reported by the response.

stop_reason
enum<string>

Why the model stopped generating. refusal can be returned as a successful HTTP response when the model declines a request.

Options disponibles:
end_turn,
max_tokens,
stop_sequence,
tool_use,
pause_turn,
refusal
stop_sequence
string | null

The stop sequence that caused the model to stop, if applicable.

usage
object

Token usage statistics.

Dernière modification le 8 septembre 2026