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

Llamar a la API con cURL

Lección 8 de 14 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. La herramienta universal para probar APIs
  2. Tu primera petición con cURL
  3. Usar el endpoint /v1/responses
  4. Opciones útiles de cURL
  5. Leer el cuerpo desde un archivo
  6. Depurar errores comunes
  7. Puntos clave

La herramienta universal para probar APIs

cURL es una herramienta de línea de comandos disponible en todos los sistemas operativos. Te permite enviar peticiones HTTP sin necesidad de instalar un SDK ni escribir un programa. Es la herramienta ideal para probar un endpoint rápidamente, depurar una petición o automatizar llamadas en un script de shell.

Tu primera petición con cURL

Así es como se envía una petición a la API de Grok con cURL:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [
      {"role": "user", "content": "Hello, introduce yourself in one sentence."}
    ]
  }'

Desglose del comando

  • curl https://api.x.ai/v1/chat/completions: envía una petición POST (implícita por el uso de -d) al endpoint.
  • -H "Authorization: Bearer $XAI_API_KEY": añade la cabecera de autenticación con tu clave.
  • -H "Content-Type: application/json": indica que el cuerpo es JSON.
  • -d '{...}': el cuerpo de la petición en formato JSON.

Usar el endpoint /v1/responses

El endpoint moderno /v1/responses ofrece una sintaxis más concisa:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "input": "Explain machine learning to me in simple terms."
  }'

Ten en cuenta que input sustituye a messages para peticiones sencillas. Puedes pasar una cadena de texto directamente en lugar de un array de mensajes.

Opciones útiles de cURL

Formatear la salida JSON

La respuesta en bruto es difícil de leer. Usa jq para formatearla:

curl -s https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Hello"}' | jq .

La opción -s (silencioso) oculta la barra de progreso de cURL.

Extraer solo la respuesta

Para obtener el texto de la respuesta sin los metadatos:

curl -s https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "messages": [{"role": "user", "content": "Hello"}]
  }' | jq -r '.choices[0].message.content'

Ver las cabeceras de respuesta

Para depurar límites de tasa o errores, añade -i para mostrar las cabeceras HTTP:

curl -i https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Test"}'

Leer el cuerpo desde un archivo

Para peticiones complejas, guarda el JSON en un archivo:

# request.json
{
  "model": "grok-4.5",
  "messages": [
    {"role": "system", "content": "You are a translator."},
    {"role": "user", "content": "Translate into French: Hello world"}
  ],
  "temperature": 0.3
}

Luego haz referencia a él con @:

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Depurar errores comunes

  • 401 Unauthorized: clave de API inválida o faltante. Comprueba con echo $XAI_API_KEY.
  • 400 Bad Request: JSON mal formado. Valida tu JSON con jq . < request.json.
  • 429 Too Many Requests: has alcanzado el límite de tasa. Espera unos segundos.
  • 404 Not Found: comprueba la URL y la ruta del endpoint.

Puntos clave

  • cURL es perfecto para probar y depurar sin escribir código.
  • Autentícate con -H "Authorization: Bearer $XAI_API_KEY".
  • Usa jq para formatear y filtrar respuestas JSON.
  • Guarda las peticiones complejas en archivos JSON separados.