Compreender o formato da resposta
Nesta página
Anatomia de uma resposta
Quando envia um pedido para POST /v1/responses, o servidor da xAI devolve um objeto JSON estruturado. Compreender cada campo deste objeto é essencial para utilizar corretamente os resultados na sua aplicação.
Estrutura completa
Eis uma resposta típica:
{
"id": "resp-abc123def456",
"object": "response",
"created_at": 1712000000,
"status": "completed",
"model": "grok-4.20-0309-reasoning",
"output": [
{
"type": "message",
"content": [
{
"type": "output_text",
"text": "Le machine learning est une branche de l'IA...",
"annotations": []
}
],
"status": "completed"
}
],
"usage": {
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
}
Campos principais
id
O identificador único da resposta, no formato resp-xxx. Vai utilizá-lo para:
- Encadear conversas com
previous_response_id - Recuperar uma resposta armazenada com
GET /v1/responses/{id} - Eliminar uma resposta com
DELETE /v1/responses/{id}
status
O estado da resposta:
| Estado | Significado |
|---|---|
completed | Resposta gerada com sucesso |
failed | Erro durante a geração |
incomplete | Resposta interrompida (limite de tokens, filtro de conteúdo) |
in_progress | Geração em curso (streaming) |
Verifique sempre o estado antes de utilizar o conteúdo da resposta no seu código.
output
Um array que contém os elementos da resposta. Cada elemento possui um type:
message: Resposta textual do modelofunction_call: Chamada de ferramenta solicitada pelo modelo
O conteúdo textual encontra-se em output[0].content[0].text. As anotações (citações, ligações) estão no array annotations do mesmo objeto.
usage
Informações de utilização, detalhadas abaixo.
Compreender o objeto usage
O objeto usage é crucial para monitorizar os seus custos:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Tokens de entrada e de saída
input_tokens: Número de tokens no seu prompt (e no histórico, se encadear conversas)output_tokens: Número total de tokens gerados, incluindo o raciocíniototal_tokens: Soma de ambos
Tokens de raciocínio
output_tokens_details.reasoning_tokens indica quantos tokens o modelo utilizou para o seu raciocínio interno. Estes tokens são faturados, mas não são visíveis na resposta textual.
No exemplo acima, dos 180 tokens de saída, 120 destinam-se ao raciocínio e apenas 60 compõem a resposta visível. Esta é uma proporção típica para modelos de raciocínio.
Custo em nano-USD
cost_in_nano_usd indica o custo exato do pedido. A conversão é simples:
Custo em USD = cost_in_nano_usd / 1.000.000.000
Para o nosso exemplo: 500000 / 1.000.000.000 = 0,0005 USD (0,0005 $).
Utilização de ferramentas no lado do servidor
Quando o modelo utiliza ferramentas integradas, o objeto usage inclui também:
{
"server_side_tool_usage_details": {
"web_search_calls": 2,
"code_interpreter_calls": 0,
"x_search_calls": 1,
"document_search_calls": 0,
"file_search_calls": 0,
"mcp_calls": 0
}
}
Isto permite-lhe saber exatamente quais as ferramentas invocadas e quantas vezes.
Extrair texto em Python
Eis um padrão robusto para extrair conteúdo textual:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Check status
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Error: status {response.status}")
# Display usage
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Pontos-chave
- Cada resposta tem um
idúnico reutilizável para encadeamento ou recuperação - Verifique sempre o
statusantes de utilizar o conteúdo - O texto localiza-se em
output[0].content[0].text - Os
reasoning_tokenssão faturados mas invisíveis na resposta - O
cost_in_nano_usddividido por mil milhões fornece o custo em dólares