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

Una solicitud POST /v1/responses sencilla

Lección 9 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Tu primera llamada exitosa
  2. Estructura de la solicitud
  3. Anatomía de la respuesta
  4. Parámetros opcionales comunes
  5. Continuar una conversación
  6. Rastrear costes
  7. Puntos clave

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_p en 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 utilizar
  • input: 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 tarde
  • status: completed cuando la generación ha finalizado
  • output: una matriz que contiene los mensajes generados
  • usage: 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.7 y top_p=0.95 y 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/responses es el más moderno y recomendado
  • Dos parámetros obligatorios: model e input
  • La respuesta se encuentra en output[0].content[0].text
  • Utiliza previous_response_id para conversaciones de varios turnos
  • El campo usage te ayuda a rastrear tu consumo de tokens