Crear una respuesta con POST /v1/responses
En esta página
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:
- Utilice el modelo
grok-4.20-0309-reasoning. - Defina instrucciones de sistema para un asistente técnico.
- 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/responseses el punto de acceso principal; requieremodeleinput.inputacepta texto plano o una matriz estructurada con roles.instructionsdefine 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.