Skip to main content
POST
Usa POST /v1/messages per inviare richieste a Claude nel formato Anthropic Messages. Gli esempi configurano l’SDK Anthropic ufficiale con l’URL di base di CometAPI e leggono la tua chiave API da $COMETAPI_KEY.
Per le definizioni dei campi e le opzioni specifiche del modello, consulta il riferimento ufficiale dell’API Messages. Per richieste compatibili con OpenAI, consulta Chat Completions.
Autenticati con x-api-key o Authorization: Bearer. L’SDK Anthropic utilizza x-api-key. Gli esempi HTTP includono anthropic-version: 2023-06-01.

Guida rapida

Gli esempi seguenti richiedono tre query di ricerca. Imposta $COMETAPI_KEY prima di eseguirli. Installa anthropic per Python o @anthropic-ai/sdk per JavaScript:
La risposta contiene un array content. Leggi i blocchi il cui type è text; i blocchi di thinking e di strumenti possono comparire prima del testo.

Controllare il thinking adattivo

Imposta thinking.type su adaptive e scegli un valore per output_config.effort. L’esempio seguente usa xhigh e legge il messaggio completato da uno stream:
Il thinking contribuisce al limite di output max_tokens. Lascia spazio anche per la risposta finale e per il thinking. Una risposta può contenere testo senza un blocco di thinking visibile. Mantieni invariati nella cronologia della conversazione tutti i blocchi di thinking restituiti . Per la configurazione del thinking specifica del modello, consulta Thinking. Gli esempi omettono temperature, top_p e top_k; consulta la documentazione dei parametri del modello selezionato prima di aggiungere controlli di sampling.

Memorizzare nella cache i Prompt

Inserisci un breakpoint della cache nel materiale di riferimento che riutilizzi tra le richieste. Salva il materiale di riferimento in un file UTF-8 reference.txt prima di eseguire questo esempio. Usa un prefisso che soddisfi la lunghezza minima memorizzabile nella cache:
Esegui nuovamente la richiesta con lo stesso modello, testo di riferimento e impostazioni di thinking. Esamina i contatori di utilizzo per determinare se la richiesta ha riutilizzato un prefisso:
  • cache_creation_input_tokens conta i token scritti nella cache.
  • cache_read_input_tokens conta i token letti dalla cache.
  • input_tokens conta l’input elaborato al di fuori di tali contatori della cache.
Nelle richieste ripetute, cache_read_input_tokens riporta quanti token di input sono stati letti dalla cache. L’esempio OpenAPI Prompt Cache contiene un riferimento fittizio completo che puoi salvare come reference.txt per provare l’esempio.

Trasmettere le risposte in streaming

Imposta stream: true per Server-Sent Events. L’SDK espone i frammenti di testo man mano che arrivano:
Un flusso di messaggi contiene message_start, eventi dei blocchi di contenuto, message_delta, e message_stop. I blocchi di contenuto possono contenere testo, ragionamento o attività degli strumenti. Per un blocco di testo, content_block_delta contiene un text_delta. Leggi l’utilizzo finale e il motivo di arresto da message_delta.

Controllo dello sforzo

Imposta output_config.effort per orientare la quantità di ragionamento. Questo esempio usa low per una breve spiegazione e attende il messaggio in streaming completato:
Usa il riferimento ufficiale riferimento sullo sforzo per scegliere un livello di sforzo. Imposta max_tokens separatamente per limitare la lunghezza dell’output.

Usa gli strumenti del server

Gli strumenti del server vengono eseguiti durante la richiesta API e restituiscono blocchi di risultato insieme a la risposta di Claude.
Recupera un documento e chiedi a Claude di usare il documento recuperato nella sua risposta. Questo esempio trasmette la risposta in Streaming e analizza sia il testo finale sia il web_fetch_tool_result blocco:
La risposta abbina un blocco server_tool_use a un web_fetch_tool_result contenente il documento recuperato o un errore dello strumento.

Restituisci i risultati degli strumenti client

Per uno strumento client, Claude restituisce un blocco tool_use. Esegui la funzione della tua applicazione e inviane il risultato in un blocco tool_result con il valore tool_use_id corrispondente. Mantieni l’intero contenuto dell’assistant tra le due richieste. Questo esempio fornisce un risultato di ordine fittizio e chiede a Claude di usare tale risultato:

Esempio di risposta

Una richiesta non-Streaming restituisce un oggetto messaggio. L’esempio seguente mostra i relativi campi text e usage con un identificatore del messaggio illustrativo:
Il motivo di arresto descrive l’azione successiva. end_turn completa la risposta, max_tokens indica che l’output ha raggiunto il limite e tool_use richiede il risultato di uno strumento client. Per un turno di uno strumento server che restituisce pause_turn, prosegui con il contenuto dell’assistant restituito invariato.

Autorizzazioni

x-api-key
string
header
obbligatorio

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

Intestazioni

anthropic-version
string
predefinito:2023-06-01

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

Esempio:

"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.

Corpo

application/json
model
string
predefinito:claude-opus-5
obbligatorio

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

Esempio:

"claude-opus-5"

messages
object[]
obbligatorio

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
obbligatorio

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.

Intervallo richiesto: x >= 1
Esempio:

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.

Intervallo richiesto: 0 <= x <= 1
top_p
number

Nucleus sampling threshold. The examples omit sampling overrides.

Intervallo richiesto: 0 <= x <= 1
top_k
integer

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

Intervallo richiesto: x >= 0
stream
boolean
predefinito: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.

Opzioni disponibili:
auto,
standard_only

Risposta

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.

Opzioni disponibili:
message
role
enum<string>

Always assistant.

Opzioni disponibili:
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.

Opzioni disponibili:
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.

Ultima modifica il 8 settembre 2026