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

Crear una respuesta con POST /v1/responses

Lección 2 de 16 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Tu primera solicitud
  2. Autenticación
  3. Solicitud mínima
  4. Con el SDK de Python
  5. Entrada simple frente a estructurada
  6. El parámetro instructions
  7. Ejercicio práctico
  8. Puntos clave

Tu primera solicitud

El punto de acceso POST /v1/responses es la puerta de entrada principal de la API de Respuestas. Aquí es donde envías tus indicaciones (prompts) y recibes las respuestas de los modelos Grok. En esta lección, aprenderás a construir y enviar tu primera solicitud.

Autenticación

Todas las solicitudes requieren un encabezado de autenticación con tu clave de API de xAI:

Authorization: Bearer $XAI_API_KEY

Puedes generar tus claves en console.x.ai. Mantenlas en secreto: nunca las subas a un repositorio de Git.

Solicitud mínima

Esta es la solicitud más simple posible:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20-0309-reasoning",
    "input": "Explain what machine learning is in 3 sentences."
  }'

Bastan dos campos:

  • model: el identificador del modelo Grok que deseas utilizar.
  • input: tu indicación, como texto plano.

Con el SDK de Python

Si utilizas el SDK de OpenAI (compatible con xAI), la sintaxis es similar:

from openai import OpenAI

client = OpenAI(
    api_key="xai-...",
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Explain what machine learning is in 3 sentences."
)

print(response.output[0].content[0].text)

Entrada simple frente a estructurada

El parámetro input acepta dos formatos.

Texto plano

{
  "model": "grok-4.20-0309-reasoning",
  "input": "What is the capital of France?"
}

Matriz estructurada

Para entradas multimodales o roles explícitos:

{
  "model": "grok-4.20-0309-reasoning",
  "input": [
    {
      "role": "user",
      "content": "Analyze this image and describe what you see."
    }
  ]
}

El formato de matriz te ofrece mayor control, especialmente para incluir imágenes o especificar diferentes roles.

El parámetro instructions

Para definir el comportamiento del sistema del modelo, utiliza instructions en lugar de añadir un mensaje de sistema dentro de input:

{
  "model": "grok-4.20-0309-reasoning",
  "instructions": "You are a French cuisine expert. Always respond including a chef's tip.",
  "input": "How do I make a successful béchamel?"
}

El campo instructions equivale al system prompt (indicación de sistema) en las Finalizaciones de Chat (Chat Completions). Define el comportamiento global del modelo para toda la conversación.

Ejercicio práctico

Intenta construir una solicitud que:

  1. Utilice el modelo grok-4.20-0309-reasoning.
  2. Defina instrucciones de sistema para un asistente técnico.
  3. Plantee una pregunta sobre Python.
curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20-0309-reasoning",
    "instructions": "You are a senior Python developer. Give concise code examples.",
    "input": "How do I read a JSON file in Python?"
  }'

Puntos clave

  • POST /v1/responses es el punto de acceso principal; requiere model e input.
  • input acepta texto plano o una matriz estructurada con roles.
  • instructions define el comportamiento de sistema del modelo.
  • La autenticación se realiza mediante el encabezado Authorization: Bearer.
  • El SDK de OpenAI es compatible con xAI cambiando el base_url.