Conectarse a la API de Grok no es complicado en sí mismo. Lo que suele bloquear a los equipos son tres cosas: de dónde sale la clave, cómo se escribe la URL base y si la clave y la dirección pertenecen al mismo proveedor. El error 401 más habitual no se debe a una clave vencida, sino a una clave de una plataforma usada contra la dirección de otra.

Este artículo recorre el proceso en este orden: vías de obtención, creación de la clave, configuración de la dirección, llamada mínima, seguridad y solución de problemas. Los nombres de los modelos y su disponibilidad se rigen por los precios de modelos de este sitio; los nombres de los menús de la consola pueden cambiar, así que guíate por lo que muestre la página real.

Nota: xAI y Grok son marcas de sus respectivos titulares; este artículo solo ofrece una explicación técnica. Las interfaces, los modelos y los precios pueden cambiar. Consulta la documentación oficial de xAI y los precios de modelos.

1. Primero define qué tipo de clave necesitas

Las claves de la API de Grok suelen provenir de dos fuentes: la consola oficial de xAI y un gateway de IA local que ofrece una entrada compatible con OpenAI. Ambas permiten llamar a Grok, pero la cuenta, el pago y el responsable de la facturación son distintos.

Criterio Consola oficial de xAI ZSQH AI Gateway
Perfil de usuario Con método de pago internacional y acceso estable Pago local, necesita factura en yuanes
Sistema de cuentas Cuenta de xAI Cuenta del gateway
Forma de pago Los métodos que admite el proveedor oficial Recarga en yuanes
URL base https://api.x.ai/v1 https://ai.zhongshangqihang.com/v1
Facturación Factura en dólares; el tipo de cambio corre por tu cuenta Factura en yuanes y uso unificado de varios modelos
Alcance de modelos Modelos propios de xAI Varios modelos habilitados en el gateway

Las claves de las dos vías no son intercambiables. Una clave oficial solo funciona con la dirección oficial, y una clave del gateway solo con la dirección del gateway. Elige primero la vía, crea después la clave y no mezcles ambas a mitad del proceso.

2. xAI oficial: pasos para obtener la clave

  1. Prepara una cuenta de xAI válida y confirma el estado de la cuenta, los términos del servicio y los requisitos de uso de tu región.
  2. Inicia sesión en la consola de xAI y localiza la sección de gestión de claves de API. El nombre del menú puede cambiar entre versiones; guíate por lo que veas en pantalla.
  3. Completa la configuración de facturación o la recarga prepaga según lo que pida la consola. Sin saldo disponible, la clave puede crearse correctamente y aun así no servir para llamar a la API.
  4. Crea una clave con un nombre que incluya proyecto y entorno, por ejemplo prod-atencion-cliente, para facilitar la rotación y la auditoría.
  5. Cópiala y guárdala inmediatamente después de crearla. La mayoría de las plataformas la muestra completa una sola vez y no permite volver a verla al cerrar la página.
  6. Si la consola ofrece opciones de cuota, permisos o restricción por IP, configúralas con el principio de mínimo privilegio; no dejes todos los permisos abiertos por defecto.
  7. Verifica con una petición mínima que la clave, la dirección y el nombre del modelo funcionan juntos.

La vía oficial encaja en equipos que solo necesitan Grok y disponen de pago y acceso internacionales estables. Si el pago o la red fallan con frecuencia, el problema deja de ser "qué tan bueno es el modelo" y pasa a ser "si hoy podemos llamar", un costo operativo que suele subestimarse.

3. Gateway: pasos para obtener la clave

  1. Abre ZSQH AI Gateway, registra una cuenta y completa la información de identidad o de empresa que corresponda.
  2. Recarga primero una cantidad pequeña para validar el pago, la acreditación y la cadena de llamadas; después completa el saldo según el uso real.
  3. Crea una clave de API en la consola, ponle el nombre del proyecto y define un límite de gasto o una alerta.
  4. Anota la URL base del gateway: https://ai.zhongshangqihang.com/v1.
  5. Envía una petición mínima con el comando curl que aparece más abajo y confirma que devuelve 200 con contenido.
  6. Cuando funcione, integra el código de negocio y guarda la clave en una variable de entorno del servidor.

El valor de la vía del gateway no está solo en "poder acceder", sino también en el pago en yuanes, la facturación unificada, el cambio entre varios modelos y la gestión de todos ellos con una sola clave. Si te conviene depende de tu forma de pago, tus requisitos de factura y los límites operativos que quieras asumir.

4. Cómo escribir la URL base y los endpoints

La URL base es el punto donde más se falla. Normalmente se escribe solo hasta /v1, porque el SDK añade la ruta posterior automáticamente; si escribes la dirección completa a mano, evita duplicar la ruta.

Elemento xAI oficial ZSQH AI Gateway
URL base https://api.x.ai/v1 https://ai.zhongshangqihang.com/v1
Endpoint de chat /chat/completions /chat/completions
Cabecera de autenticación Authorization: Bearer <clave> Authorization: Bearer <clave>
Nombre del modelo Según la lista oficial Según los precios de modelos del sitio

Un error frecuente es escribir https://api.x.ai/v1/v1/chat/completions, o dejar una barra extra al final de la URL base antes de concatenar la ruta. Otro error habitual consiste en usar la cabecera x-api-key de estilo Anthropic con Grok. La entrada compatible con OpenAI de Grok utiliza autenticación Bearer.

5. Verificación con una llamada mínima

Empieza con curl para descartar problemas de código. El siguiente comando envía un solo mensaje corto; si devuelve 200 y un campo choices, la clave, la URL base y el nombre del modelo coinciden.

export GROK_API_KEY="sk-tu-clave"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GROK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "messages": [{"role": "user", "content": "Responde solo OK"}],
    "max_tokens": 16
  }'

Los proyectos en Python pueden reutilizar el SDK de OpenAI cambiando solo la clave y la URL base:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GROK_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="grok-4",
    messages=[{"role": "user", "content": "Explica qué es un gateway de API en tres frases."}],
    max_tokens=256,
)
print(resp.choices[0].message.content)

No escribas el nombre del modelo de memoria. Los modelos habilitados pueden variar entre cuentas y gateways; usa la lista de precios de modelos o la de la consola. Un nombre incorrecto suele devolver 404 o model not found, y no es un problema de la clave.

6. Configuración segura de la clave

  1. Guarda la clave solo en variables de entorno del servidor o en un gestor de secretos; nunca la incluyas en el repositorio de código.
  2. No incrustes la clave en el paquete del frontend, en peticiones del navegador ni en el instalador de una aplicación móvil. El frontend debe llamar a tu propio backend.
  3. Usa una clave por proyecto y separa pruebas de producción; así podrás aplicar límites, rotar claves y rastrear el consumo.
  4. En los registros, guarda solo los primeros caracteres de la clave o un hash, nunca el valor completo.
  5. Si una persona deja el equipo, termina un proyecto o sospechas una filtración, revoca la clave y crea una nueva de inmediato.
  6. Revisa periódicamente la curva de consumo. Ante llamadas anómalas, desactiva primero la clave y luego investiga; no empieces cambiando el código de negocio.

Las consecuencias típicas de una filtración no se limitan a que "otra persona gaste tu dinero": se descontrolan al mismo tiempo los datos, la cuota y la factura. Tratar la clave como la contraseña de una base de datos evita muchos problemas por adelantado.

7. Errores de configuración frecuentes

Síntoma Causa habitual Qué hacer
401 La clave y la URL base no coinciden; la clave tiene espacios o saltos de línea Confirma que provienen del mismo lugar y vuelve a copiar la clave
404 Ruta duplicada; endpoint mal escrito La URL base solo hasta /v1; el endpoint es /chat/completions
model not found Nombre del modelo mal escrito o no habilitado en la cuenta Copia el nombre desde la página de precios o la consola
429 Se superó el límite de frecuencia, concurrencia o tokens Reduce la concurrencia y reintenta con retroceso
insufficient quota Saldo insuficiente o límite de la clave alcanzado Recarga y revisa el límite configurado en la clave
Timeout Enlace de red, proxy o salida larga Revisa la salida y define timeouts de conexión y lectura razonables

Al diagnosticar, conserva primero el ID de la petición y el código de estado de la respuesta, y después modifica la petición. Sin esos datos, solo puedes adivinar.

Preguntas frecuentes

¿La clave y la URL base deben venir del mismo proveedor?

Sí. Una clave oficial va con la dirección oficial, y una clave del gateway con la dirección del gateway. Mezclarlas suele producir un 401; en algunos casos aparece un 404 o un error de permisos.

¿Puedo poner la clave en el navegador?

No es recomendable. El código del navegador es visible para el usuario y la clave se extrae con facilidad. Lo correcto es que el frontend llame a tu backend, y que el backend guarde la clave y reenvíe las peticiones.

¿Una sola clave puede llamar a varios modelos?

En el modo gateway, normalmente sí: basta con indicar el nombre del modelo en la petición, siempre que la cuenta tenga habilitado ese modelo. En una cuenta oficial, los modelos disponibles dependen de la consola.

¿Qué hago si la clave se filtra?

Revoca o desactiva la clave en la consola de inmediato, crea una nueva y revisa el consumo y la factura recientes. No te limites a cambiar la cadena en el código dejando la clave antigua activa.

¿Por qué una clave recién copiada sigue devolviendo 401?

Comprueba si copiaste espacios, saltos de línea o comillas de más, y confirma que la URL base coincide. Si sigue fallando, prueba directamente con curl para descartar la configuración del SDK y el entorno del proxy.

Siguientes pasos

Si necesitas un solo punto de entrada para llamar a Grok y a otros modelos, crea primero una clave de prueba en ZSQH AI Gateway y valida con una petición mínima antes de integrar el negocio. La disponibilidad y los precios de los modelos se rigen por los precios de modelos.

Lecturas relacionadas: