Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Compreender o formato da resposta

Aula 4 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Anatomia de uma resposta
  2. Estrutura completa
  3. Campos principais
  4. Compreender o objeto usage
  5. Utilização de ferramentas no lado do servidor
  6. Extrair texto em Python
  7. Pontos-chave

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:

EstadoSignificado
completedResposta gerada com sucesso
failedErro durante a geração
incompleteResposta interrompida (limite de tokens, filtro de conteúdo)
in_progressGeraçã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 modelo
  • function_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ínio
  • total_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 status antes de utilizar o conteúdo
  • O texto localiza-se em output[0].content[0].text
  • Os reasoning_tokens são faturados mas invisíveis na resposta
  • O cost_in_nano_usd dividido por mil milhões fornece o custo em dólares