La dificultad de conectar la API de Grok no suele estar en escribir la solicitud, sino en tres cosas: que la clave y la dirección correspondan entre sí, qué endpoint usar y de dónde copiar el nombre del modelo. Si aciertas en esas tres, la primera llamada funciona en pocos minutos; si fallas, lo más habitual es ver un 401, un 404 o un "model not found".

Este artículo sigue la documentación oficial de xAI y recorre, en orden, la cuenta y la clave, la URL base, los nombres de modelo, curl, Python, streaming y llamadas a funciones, la solución de errores y la lista de migración. Los precios y los modelos disponibles cambian; antes de integrar, revisa la página Models de xAI y los precios de modelos del sitio.

Nota: xAI y Grok son marcas de sus respectivos titulares, y OpenAI es marca de su titular. Este artículo solo ofrece una explicación técnica de la integración.

1. Primero elige la vía: consola oficial o gateway compatible

La clave de la API de Grok suele venir de dos fuentes: la consola oficial de xAI o un gateway local que ofrece una entrada compatible con OpenAI. El formato de las solicitudes es parecido en ambas vías, pero la cuenta, el pago y la URL base son distintos, y las claves no se pueden mezclar.

Aspecto xAI oficial ZSQH AI Gateway
Consola console.x.ai ai.zhongshangqihang.com
URL base https://api.x.ai/v1 https://ai.zhongshangqihang.com/v1
Pago Según los métodos que admite el proveedor Recarga en RMB; consulta las condiciones del sitio
Ideal para Equipos con acceso estable y pago internacional Acceso local, factura unificada y cambio entre modelos

Elige la vía antes de crear la clave. Si pones una clave oficial en la dirección del gateway, o al contrario, lo normal es recibir un 401. El registro en el gateway está aquí; que lo necesites depende de tu red, tu forma de pago y tus requisitos de factura.

2. Seis pasos para crear la clave

  1. Regístrate e inicia sesión en la consola. La vía oficial es console.x.ai; la vía del gateway empieza en la página de registro.
  2. Configura la facturación o recarga saldo. Sin cuota disponible, la clave puede crearse pero las llamadas fallarán.
  3. Entra en la página de claves de API, crea una y ponle un nombre que identifique el proyecto y el entorno, por ejemplo prod-qa-2026-10.
  4. Copia la clave completa de inmediato y guárdala en una variable de entorno del servidor o en un gestor de secretos. La mayoría de las consolas solo la muestran una vez.
  5. Aplica el mínimo privilegio: límites de gasto, IP o permisos de equipo. Si la consola no ofrece una opción, no fuerces una solución alternativa.
  6. Verifica con una solicitud mínima que la clave, la URL base y el nombre del modelo coinciden.

No escribas la clave en el código del frontend, en un repositorio de Git ni en un chat. Crea claves distintas para pruebas y producción, de modo que una rotación no afecte a toda la operación.

3. URL base y endpoints: escribe solo hasta /v1

La URL base oficial es https://api.x.ai/v1. Hay dos puntos importantes: la URL base termina en /v1 y no debes añadirle /chat/completions; el endpoint concreto lo determina el SDK o la ruta de la solicitud.

Hoy la documentación oficial recomienda POST /v1/responses (Responses API). La ruta compatible con OpenAI POST /v1/chat/completions sigue funcionando, pero está marcada como legacy y las funciones nuevas llegan primero a Responses API. Para proyectos nuevos conviene usar Responses API; el código existente de Chat Completions puede seguir ejecutándose, con la aceptación de que ya no es la ruta principal.

La solicitud curl mínima es la siguiente; la autenticación usa siempre Authorization: Bearer:

export XAI_API_KEY="tu_clave"

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Explica en tres frases qué es una puerta de enlace de API.",
    "store": false
  }'

store controla si la solicitud y la respuesta se guardan en el servidor. La documentación oficial indica que Responses conserva los datos 30 días por defecto; si trabajas con contenido sensible, conviene fijar store: false y confirmar que, al desactivarlo, no podrás continuar la conversación con previous_response_id.

4. Cómo escribir el nombre del modelo: copia el ID, no lo adivines

El nombre del modelo es un identificador de la API, no el nombre comercial de una página de producto. La página Models oficial enumera los ID disponibles, la longitud de contexto y el tramo de facturación. Estos son algunos ejemplos de la documentación de octubre de 2026, solo para mostrar el formato:

ID del modelo Contexto Uso habitual
grok-4.7 500k Preguntas generales, programación, agentes
grok-4.3 1M Documentos largos y conversaciones extensas
grok-4.20-0309-reasoning 1M Tareas que requieren razonamiento explícito
grok-build-0.1 256k Flujos de programación y compilación

Los modelos se publican y se retiran, y los nombres pueden llevar sufijo de fecha. Antes de ponerlos en producción, cópialos de la página Models oficial o de los precios de modelos del sitio; no los escribas de memoria. Los modelos con -reasoning suelen devolver un proceso de razonamiento, y su latencia y estructura de costo difieren de las de un modelo normal: pruébalos primero con poco tráfico.

5. Primera llamada con Python

xAI ofrece su propio SDK y también admite el SDK de OpenAI. Los equipos que ya tienen código de OpenAI solo necesitan cambiar base_url y api_key para empezar:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.7",
    input="Explica en tres frases qué es una puerta de enlace de API.",
    store=False,
)

print(response.output_text)

output_text es una propiedad de conveniencia del SDK, útil para resultados de texto plano. Si necesitas leer razonamiento, llamadas a herramientas o citas, recorre response.output y decide según el campo type; no supongas que el texto siempre está en un índice fijo.

6. Streaming y llamadas a funciones

El streaming usa SSE: se envía "stream": true en la solicitud y el cliente lee los incrementos por partes. La documentación oficial advierte que los modelos de razonamiento pueden tardar bastante en generar, así que con streaming hay que ampliar el tiempo de espera del cliente para que la conexión no se cierre antes de tiempo. Así se llama a un endpoint compatible con el SDK de OpenAI:

stream = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": "Explica en tres frases qué es SSE."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Las llamadas a funciones tienen cinco pasos: define el nombre, la descripción y el esquema JSON de la herramienta; inclúyela en la solicitud; el modelo devuelve function_call; ejecutas la función en tu entorno; y devuelves el resultado al modelo para que continúe. En Responses API la definición de herramientas es plana, con los campos type: "function", name, description y parameters.

Dos detalles que se pasan por alto: en modo streaming, los argumentos de una llamada a función pueden llegar en un bloque completo en lugar de token por token; y las herramientas de búsqueda del lado del servidor pueden facturarse por uso, según la página oficial de precios. Cuantas más herramientas y más vagas sean sus descripciones, más probable es que el modelo elija la equivocada; empieza por limitar la cantidad y afinar los parámetros.

7. Errores frecuentes: mira primero el código de estado

Código Causa habitual Qué hacer
401 Falta la clave, es incorrecta o no corresponde a la URL base Revisa el encabezado Authorization y que la dirección sea la correcta
403 La cuenta o la clave no tienen permiso, o hay restricciones regionales o de términos Consulta permisos y estado de la cuenta en la consola
404 Ruta mal escrita o modelo inexistente Verifica /v1/responses y el ID del modelo
400 / 422 Formato incorrecto de algún campo del cuerpo Contrasta los campos con la referencia de la API
429 Se superó el límite de solicitudes o de concurrencia Reintenta con retroceso exponencial y reduce la concurrencia
Tiempo de espera Generación lenta del modelo de razonamiento o red lenta Amplía el timeout, usa streaming y registra los tiempos

A veces el saldo insuficiente no se manifiesta como 429; el código y el mensaje exactos dependen de la consola y de la documentación oficial. El orden recomendado de diagnóstico es: código de estado, mensaje de error y, solo al final, cambios en el prompt. Ningún prompt, por bueno que sea, arregla una URL base equivocada.

8. Lista de migración antes de salir a producción

  1. Guarda la clave en variables de entorno del servidor y confirma que no entra en el paquete del frontend ni en los registros.
  2. Fija la URL base y prohíbe construir endpoints a mano en el código de negocio.
  3. Crea una tabla de correspondencia de modelos con el anterior, el nuevo, el contexto y el tramo de facturación.
  4. Usa /v1/responses en proyectos nuevos; si un proyecto antiguo sigue con Chat Completions, márcalo como legacy y planifica la migración.
  5. Unifica los tiempos de espera, los reintentos y la cancelación en streaming y sin streaming.
  6. Configura retroceso exponencial para 429 y 5xx, sin reintentos ilimitados.
  7. Registra el ID de solicitud, el modelo, el consumo de tokens y la latencia para conciliar y diagnosticar.
  8. Prueba primero con una función no crítica y observa una semana antes de aumentar el tráfico.

Preguntas frecuentes

¿Qué URL base se usa con la API de Grok?

La oficial es https://api.x.ai/v1; en el gateway, usa la dirección que indique su consola. Escribe solo hasta /v1, sin el endpoint concreto.

¿Por qué el SDK de OpenAI puede llamar a Grok?

xAI ofrece una estructura de solicitud compatible con OpenAI, sobre todo en Chat Completions; Responses API también se puede llamar con responses.create del SDK de OpenAI. Basta con apuntar base_url a xAI, pero el nombre del modelo y algunos parámetros siguen las reglas de xAI.

¿La API de Grok y la de OpenAI son lo mismo?

No. Son servicios de empresas distintas que comparten una forma de interfaz compatible. Las claves, la facturación, los modelos y las políticas de datos son diferentes y no se pueden mezclar.

¿Es obligatorio usar Responses API?

En proyectos nuevos, conviene. La documentación oficial ya marca Chat Completions como legacy y las capacidades nuevas llegan primero a Responses API; los sistemas existentes pueden planificar la migración según su costo, sin cambiar de la noche a la mañana.

¿Cómo se conectan los equipos en China continental de forma más estable?

Primero determina si el problema es de red, de pago o de cumplimiento. Si solo se trata de acceso y liquidación, puedes evaluar un gateway compatible con OpenAI; si los datos no pueden salir de la red interna, considera un despliegue privado u otra arquitectura. La decisión depende de tus restricciones reales.

Resumen

Conectar la API de Grok se puede resumir en una frase: elige bien el origen de la clave, escribe la URL base solo hasta /v1, copia el nombre del modelo de la página oficial y prefiere Responses API en proyectos nuevos. Lo demás —streaming, llamadas a funciones y manejo de errores— son detalles que se añaden sobre esa cadena principal.

Si necesitas gestionar varios modelos y una factura común, puedes empezar en la página de registro; los modelos y la facturación vigentes están en los precios de modelos.

Lecturas relacionadas: