La tua prima richiesta spiegata
Una spiegazione riga per riga di una chiamata Messages: cosa fa ogni campo e cosa viene restituito.
La guida rapida ti permette di ottenere una risposta. Questa pagina spiega il significato di ogni sua parte, così potrai scrivere autonomamente la richiesta successiva.
La richiesta
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"}]
}'| Campo | Obbligatorio | A cosa serve |
|---|---|---|
model | sì | Quale modello eseguire. Deve corrispondere a un ID presente in /v1/models esattamente. |
max_tokens | sì | Limite massimo rigido per l' output. Il modello si ferma a questo limite anche a metà frase. È un controllo dei costi, non un obiettivo. |
messages | sì | La conversazione fino a questo momento, a partire dal messaggio più vecchio. Ogni voce ha un role (user o assistant) e content. |
system | no | Istruzioni che si applicano all'intera conversazione. Un campo di primo livello, non un messaggio con role: system. |
temperature | no | 0–1. Un valore più basso rende il comportamento più deterministico. Lascialo non impostato, a meno che tu non abbia un motivo per farlo. |
stream | no | true restituisce eventi inviati dal server anziché un unico corpo JSON. Vedi Streaming. |
La risposta
{
"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}
}contentè un array, non una stringa. Il testo si trova incontent[0].text. Trattarlo come una stringa è il bug più comune nei client.stop_reasonindica perché la generazione è terminata:end_turn(completata),max_tokens(raggiunto il limite impostato — la risposta è troncata),stop_sequence, oppuretool_use.usageè ciò su cui si basa la fatturazione. Registralo nei log; è l'unica base affidabile per l'attribuzione dei costi.
Se
stop_reason è max_tokens, la risposta è stata interrotta. Aumenta max_tokens oppure chiedi una risposta più breve — non riprovare alla cieca: paghi anche per l'output troncato.Conversazioni con più scambi
L'API non mantiene lo stato. Per continuare una conversazione devi reinviare l'intera cronologia, incluse le risposte precedenti del modello:
{
"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?"}
]
}Poiché la cronologia viene reinviata a ogni scambio, i token di input aumentano con la conversazione, così come il costo. Ecco perché le sessioni lunghe degli agenti diventano costose. Caching dei prompt e gestione del contesto affrontano entrambi direttamente questo problema.