Ir al contenido principal
Español— Elegir un idioma
Menú

Entender el formato de respuesta

Lección 4 de 16 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Anatomía de una respuesta
  2. Estructura completa
  3. Campos principales
  4. Comprender el objeto usage
  5. Uso de herramientas del lado del servidor
  6. Extraer texto en Python
  7. Puntos clave

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:

EstadoSignificado
completedRespuesta generada correctamente
failedError durante la generación
incompleteRespuesta interrumpida (límite de tokens, filtro de contenido)
in_progressGeneració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 modelo
  • function_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 razonamiento
  • total_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 status antes de utilizar el contenido
  • El texto se encuentra en output[0].content[0].text
  • Los reasoning_tokens se facturan pero son invisibles en la respuesta
  • Divide cost_in_nano_usd por mil millones para obtener el coste en dólares