Una solicitud POST /v1/responses sencilla
En esta página
Actualizado el 3 de noviembre de 2026, según las mejores prácticas y la referencia de la API de xAI: la temperatura está limitada a 1, y xAI recomienda 0,7 con
top_pen 0,95. Fuente: Mejores prácticas.
Tu primera llamada exitosa
Ya tienes tu cuenta, tu clave de API y un SDK instalado. Es hora de enviar tu primera solicitud a la API de Grok y comprender la estructura de la respuesta. Esta lección se centra en el endpoint principal, /v1/responses, el más moderno y recomendado.
Estructura de la solicitud
El endpoint POST /v1/responses requiere al menos dos parámetros:
model: el ID del modelo que se va a utilizarinput: el texto de tu solicitud (o una matriz de contenido para casos avanzados)
Solicitud mínima en Python
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1"
)
response = client.responses.create(
model="grok-4.5",
input="¿Cuál es el lenguaje de programación más utilizado en 2026?"
)
print(response.output[0].content[0].text)
Con instrucciones de sistema
El parámetro instructions te permite definir el comportamiento del modelo:
response = client.responses.create(
model="grok-4.5",
instructions="Eres un experto en desarrollo web. Responde de forma concisa.",
input="¿Cuál es la diferencia entre SSR y SSG?"
)
Anatomía de la respuesta
La API devuelve un objeto JSON estructurado. Estos son los campos principales:
{
"id": "resp-abc123",
"object": "response",
"status": "completed",
"model": "grok-4.5",
"output": [
{
"type": "message",
"content": [
{
"type": "output_text",
"text": "La respuesta del modelo aparece aquí."
}
],
"status": "completed"
}
],
"usage": {
"input_tokens": 42,
"output_tokens": 156,
"total_tokens": 198
}
}
Campos importantes
id: el ID único de la respuesta, útil para recuperarla más tardestatus:completedcuando la generación ha finalizadooutput: una matriz que contiene los mensajes generadosusage: contadores de tokens para rastrear tu consumo
Parámetros opcionales comunes
Controlar la creatividad
response = client.responses.create(
model="grok-4.5",
input="Sugiere un nombre para una startup de IA.",
temperature=0.7, # el valor que recomienda xAI
top_p=0.95,
)
- La API acepta una temperatura de 0 a 2, pero limita cualquier valor superior a 1
- xAI recomienda
temperature=0.7ytop_p=0.95y aconseja no desviarse de ellos: la calidad suele disminuir - Para obtener más creatividad, pídela en el prompt («sugiere nombres inesperados»)
Limitar la longitud
response = client.responses.create(
model="grok-4.5",
input="Resume el concepto de aprendizaje automático.",
max_output_tokens=200 # Limita la respuesta
)
Activar el razonamiento
Para los modelos de razonamiento, ajusta el esfuerzo de pensamiento:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Resuelve este problema: si 3x + 7 = 22, ¿cuál es x?",
reasoning={"effort": "high"}
)
Los niveles posibles son low, medium y high.
Continuar una conversación
El endpoint /v1/responses admite conversaciones de varios turnos mediante el parámetro previous_response_id:
# Primer mensaje
r1 = client.responses.create(
model="grok-4.5",
input="Estoy construyendo una API en Python."
)
# Segundo mensaje (el modelo recuerda el contexto)
r2 = client.responses.create(
model="grok-4.5",
input="¿Qué framework recomiendas?",
previous_response_id=r1.id
)
Este enfoque es más sencillo que gestionar tú mismo el historial de mensajes.
Rastrear costes
El campo usage de la respuesta te permite calcular el coste de cada llamada. El campo output_tokens_details.reasoning_tokens muestra cuántos tokens se utilizaron en el razonamiento interno del modelo (estos tokens se facturan pero no aparecen en la respuesta).
Puntos clave
- El endpoint
POST /v1/responseses el más moderno y recomendado - Dos parámetros obligatorios:
modeleinput - La respuesta se encuentra en
output[0].content[0].text - Utiliza
previous_response_idpara conversaciones de varios turnos - El campo
usagete ayuda a rastrear tu consumo de tokens