Formato della risposta: id, choices e finish_reason
In questa pagina
Aggiornato il 3 novembre 2026 in base al riferimento dell’API Chat Completions di xAI: per
finish_reasonsono documentati solostop,lengthe, nello streaming,end_turnonull; i valoritool_callsecontent_filterdella versione precedente non sono elencati e le chiamate agli strumenti vengono rilevate tramitemessage.tool_calls.max_tokensè deprecato a favore dimax_completion_tokens. Fonte: Chat Completions.
Anatomia di una risposta Chat Completions
Ogni chiamata all’endpoint Chat Completions restituisce un oggetto JSON strutturato con campi standardizzati. Comprendere questa struttura è essenziale per estrarre correttamente i dati, gestire i casi limite ed eseguire il debug delle tue integrazioni.
Struttura completa della risposta
Ecco un esempio di una risposta tipica restituita dall’API:
{
"id": "chatcmpl-abc123xyz",
"object": "chat.completion",
"created": 1712345678,
"model": "grok-4.20-0309-reasoning",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Deep learning is a branch of machine learning..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 156,
"total_tokens": 198
},
"system_fingerprint": "fp_abc123"
}
Campi di primo livello
id: Identificatore univoco per il completamento (formatochatcmpl-...). Utile per il tracciamento e il debug.object: Sempre"chat.completion". Ti permette di distinguere questo tipo di risposta da altri endpoint.created: Timestamp Unix del momento in cui è stata creata la risposta.model: Il modello che ha generato la risposta. Potrebbe differire leggermente dal modello richiesto se utilizzi un alias.choices: Array contenente la risposta o le risposte generate.usage: Contatori di token per la fatturazione.system_fingerprint: Impronta digitale della configurazione di sistema utilizzata.
L’array choices
Il campo choices è un array che solitamente contiene un singolo elemento (indice 0). Ogni elemento contiene:
index: Posizione nell’array (inizia da 0)message: Oggetto conrole(sempre"assistant") econtent(il testo generato)finish_reason: Il motivo per cui la generazione si è interrotta
Per estrarre la risposta testuale:
# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;
Valori di finish_reason
Il campo finish_reason indica perché il modello ha smesso di generare testo:
stop
"finish_reason": "stop"
Il modello ha terminato la sua risposta naturalmente. Questo è il caso più comune e desiderabile: il modello ha detto tutto ciò che doveva dire.
length
"finish_reason": "length"
La generazione si è interrotta perché è stato raggiunto il limite di output: max_completion_tokens, che sostituisce il deprecato max_tokens, e conta solo la risposta visibile. La risposta è quindi troncata: aumenta il limite o riavvia una richiesta di continuazione.
end_turn o null nello streaming
Nello streaming, ogni chunk intermedio riporta "end_turn" o null in finish_reason; solo il chunk finale indica il motivo dell’arresto.
Cosa non documenta il riferimento
Il riferimento API di xAI documenta solo questi valori. Non menziona né content_filter né il valore restituito durante una chiamata a uno strumento: per sapere se il modello richiede uno strumento, controlla la presenza di message.tool_calls piuttosto che il valore di finish_reason.
Gestione dei diversi casi
In produzione, devi controllare finish_reason per adattare il tuo comportamento:
choice = response.choices[0]
if choice.message.tool_calls:
# Il modello vuole chiamare uno o più strumenti
for tool_call in choice.message.tool_calls:
print(f"Tool requested: {tool_call.function.name}")
elif choice.finish_reason == "length":
# Risposta troncata: notifica l'utente o continua
print(choice.message.content)
print("[Risposta troncata: aumenta max_completion_tokens]")
else:
# Risposta completa
print(choice.message.content)
Punti chiave
- La risposta contiene un
idunivoco, un arraychoicese un oggettousage - Il testo generato si trova in
choices[0].message.content finish_reasonindica perché la generazione si è interrotta: il riferimento documentastopelength(eend_turnonullnello streaming)- Controlla
finish_reasonper individuare risposte troncate emessage.tool_callsper le chiamate agli strumenti - Il
system_fingerprintidentifica la configurazione di sistema utilizzata per la generazione