Entender el formato de respuesta
En esta página
Anatomía de una respuesta
Cuando envías una petición a POST /v1/responses, el servidor de xAI devuelve un objeto JSON estructurado. Comprender cada campo de este objeto es esencial para utilizar correctamente los resultados en tu aplicación.
Estructura completa
Esta es una respuesta 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 principales
id
El identificador único de la respuesta, con el formato resp-xxx. Lo utilizarás para:
- Encadenar conversaciones mediante
previous_response_id - Recuperar una respuesta almacenada con
GET /v1/responses/{id} - Eliminar una respuesta con
DELETE /v1/responses/{id}
status
El estado de la respuesta:
| Estado | Significado |
|---|---|
completed | Respuesta generada correctamente |
failed | Error durante la generación |
incomplete | Respuesta interrumpida (límite de tokens, filtro de contenido) |
in_progress | Generación en curso (streaming) |
Comprueba siempre el estado antes de utilizar el contenido de la respuesta en tu código.
output
Un array que contiene los elementos de la respuesta. Cada elemento tiene un type:
message: Respuesta de texto del modelofunction_call: Llamada a herramienta solicitada por el modelo
El contenido de texto se encuentra en output[0].content[0].text. Las anotaciones (citas, enlaces) están en el array annotations del mismo objeto.
usage
Información sobre el uso, detallada a continuación.
Comprender el objeto usage
El objeto usage es crucial para hacer un seguimiento de tus costes:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Tokens de entrada y salida
input_tokens: Número de tokens en tu prompt (y en el historial si encadenas conversaciones)output_tokens: Número total de tokens generados, incluido el razonamientototal_tokens: Suma de ambos
Tokens de razonamiento
output_tokens_details.reasoning_tokens indica cuántos tokens ha utilizado el modelo para su razonamiento interno. Estos tokens se facturan, pero no son visibles en la respuesta de texto.
En el ejemplo anterior, de los 180 tokens de salida, 120 corresponden al razonamiento y solo 60 componen la respuesta visible. Esta es una proporción típica para los modelos de razonamiento.
Coste en nano-USD
cost_in_nano_usd proporciona el coste exacto de la petición. La conversión es sencilla:
Coste en USD = cost_in_nano_usd / 1.000.000.000
Para nuestro ejemplo: 500000 / 1.000.000.000 = 0,0005 USD (0,0005 $).
Uso de herramientas del lado del servidor
Cuando el modelo utiliza herramientas integradas, el objeto usage también incluye:
{
"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
}
}
Esto te permite saber exactamente qué herramientas se han invocado y cuántas veces.
Extraer texto en Python
Este es un patrón robusto para extraer contenido de texto:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Comprobar el estado
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Error: estado {response.status}")
# Mostrar el uso
print(f"Tokens utilizados: {response.usage.total_tokens}")
print(f"Coste: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Puntos clave
- Cada respuesta tiene un
idúnico reutilizable para encadenar o recuperar - Comprueba siempre el
statusantes de utilizar el contenido - El texto se encuentra en
output[0].content[0].text - Los
reasoning_tokensse facturan pero son invisibles en la respuesta - Divide
cost_in_nano_usdpor mil millones para obtener el coste en dólares