Formato da resposta: id, choices e finish_reason
Nesta página
Atualizado a 3 de novembro de 2026 com base na referência da API Chat Completions da xAI: apenas
stop,lengthe, em streaming,end_turnounullestão documentados parafinish_reason; os valorestool_callsecontent_filterda versão anterior não constam na lista, e as chamadas de ferramentas são detetadas através demessage.tool_calls.max_tokensestá obsoleto em favor demax_completion_tokens. Fonte: Chat Completions.
Anatomia de uma resposta Chat Completions
Cada chamada ao endpoint Chat Completions devolve um objeto JSON estruturado com campos padronizados. Compreender esta estrutura é essencial para extrair dados corretamente, gerir casos limite e depurar as suas integrações.
Estrutura completa da resposta
Eis um exemplo de uma resposta típica devolvida pela 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"
}
Campos de nível superior
id: Identificador único da conclusão (formatochatcmpl-...). Útil para rastreio e depuração.object: Sempre"chat.completion". Permite distinguir este tipo de resposta de outros endpoints.created: Timestamp Unix do momento em que a resposta foi criada.model: O modelo que gerou a resposta. Pode diferir ligeiramente do modelo solicitado se utilizar um alias.choices: Matriz que contém a resposta ou respostas geradas.usage: Contadores de tokens para faturação.system_fingerprint: Impressão digital da configuração do sistema utilizada.
A matriz choices
O campo choices é uma matriz que geralmente contém um único elemento (índice 0). Cada elemento contém:
index: Posição na matriz (começa em 0)message: Objeto comrole(sempre"assistant") econtent(o texto gerado)finish_reason: O motivo pelo qual a geração parou
Para extrair a resposta de texto:
# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;
Valores de finish_reason
O campo finish_reason indica por que motivo o modelo parou de gerar texto:
stop
"finish_reason": "stop"
O modelo concluiu a sua resposta naturalmente. Este é o caso mais comum e desejável: o modelo disse tudo o que tinha a dizer.
length
"finish_reason": "length"
A geração parou porque o limite de saída foi atingido — max_completion_tokens, que substitui o agora obsoleto max_tokens, e conta apenas a resposta visível. A resposta está, portanto, truncada: aumente o limite ou reinicie um pedido de continuação.
end_turn ou null em streaming
Em streaming, cada bloco intermédio transporta "end_turn" ou null em finish_reason; apenas o bloco final indica o motivo da paragem.
O que a referência não documenta
A referência da API da xAI documenta apenas estes valores. Não menciona nem content_filter nem o valor devolvido durante uma chamada de ferramenta: para saber se o modelo solicita uma ferramenta, verifique a presença de message.tool_calls em vez do valor de finish_reason.
Gestão de diferentes casos
Em produção, deve verificar finish_reason para adaptar o seu comportamento:
choice = response.choices[0]
if choice.message.tool_calls:
# O modelo quer chamar uma ou mais ferramentas
for tool_call in choice.message.tool_calls:
print(f"Tool requested: {tool_call.function.name}")
elif choice.finish_reason == "length":
# Resposta truncada: notificar o utilizador ou continuar
print(choice.message.content)
print("[Truncated response: increase max_completion_tokens]")
else:
# Resposta completa
print(choice.message.content)
Pontos-chave
- A resposta contém um
idúnico, uma matrizchoicese um objetousage - O texto gerado encontra-se em
choices[0].message.content finish_reasonindica por que motivo a geração parou: a referência documentastopelength(eend_turnounullem streaming)- Verifique
finish_reasonpara detetar respostas truncadas emessage.tool_callspara chamadas de ferramentas - O
system_fingerprintidentifica a configuração do sistema utilizada para a geração