URL base y primera solicitud
En esta página
La API de gestión: un plano de control independiente
La API de gestión de xAI es distinta de la API de inferencia que utilizas para enviar indicaciones a Grok. Te permite administrar tus recursos: crear y gestionar claves de API, configurar la facturación, supervisar el uso y controlar el acceso de tu equipo. Toda esta administración se realiza a través de una URL dedicada.
URL base
Esta separación no es un detalle de implementación: refleja una diferencia fundamental entre ambas API. Una consume tokens y ejecuta modelos; la otra administra, factura y concede permisos. Mantenerlas en dos dominios y con dos conjuntos de claves distintos garantiza que, si roban una clave de aplicación, nunca podrán crear otras claves ni leer tu información de facturación.
https://management-api.x.ai
No la confundas con https://api.x.ai, que es la URL para las llamadas de inferencia (completados de chat, incrustaciones, etc.). Todas las solicitudes de gestión (claves, facturación, analíticas) pasan por management-api.x.ai.
Autenticación en la API de gestión
El mecanismo de autenticación es idéntico (un token Bearer en la cabecera Authorization), pero la clave en sí no lo es. Esta es la confusión más habitual al empezar y provoca un error 401 completamente opaco: nada en el mensaje de error indica que simplemente has presentado la clave correcta a la API equivocada.
curl https://management-api.x.ai/auth/management-keys/validation \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Esta solicitud de validación (GET /auth/management-keys/validation) te permite verificar que tu clave de gestión es válida y está activa. Es el punto de entrada más sencillo para probar tu configuración.
Clave de gestión frente a clave de inferencia
- Clave de gestión: concede acceso a los puntos finales de
management-api.x.ai(administración, facturación, analíticas). - Clave de inferencia: concede acceso a los puntos finales de
api.x.ai(chat, incrustaciones, imágenes).
Ambos tipos de clave se generan desde la consola de xAI, pero sus ámbitos difieren. Una clave de inferencia no puede acceder a los puntos finales de gestión, y viceversa.
Estructura de los puntos finales
Los puntos finales de la API de gestión siguen una organización lógica:
/auth/teams/{teamId}/api-keys— gestión de claves de API/auth/api-keys/{apiKeyId}— operaciones sobre una clave específica/auth/teams/{teamId}/models— modelos accesibles/auth/teams/{teamId}/endpoints— puntos finales ACL disponibles/v1/billing/teams/{teamId}/— facturación y analíticas
El parámetro teamId es el identificador de tu equipo en la consola de xAI y estructura casi todos los puntos finales. Cada equipo tiene sus propias claves, cuotas y configuraciones de facturación, lo que lo convierte en la unidad de aislamiento natural: separar dos proyectos en dos equipos también separa sus presupuestos y accesos sin necesidad de configuración adicional.
Tu primera solicitud de gestión
Aquí tienes un ejemplo completo para validar tu configuración:
# Define tu clave de gestión
export MANAGEMENT_API_KEY="xai-mgmt-..."
# Valida la clave
curl -s https://management-api.x.ai/auth/management-keys/validation \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool
Si la respuesta contiene la información de tu equipo y de tu clave, tu configuración funciona correctamente. Si obtienes un error 401, verifica que estás usando una clave de gestión (no una clave de inferencia).
Puntos clave
- La API de gestión usa
https://management-api.x.ai, distinta dehttps://api.x.ai - La autenticación utiliza un token Bearer en la cabecera
Authorization - Las claves de gestión y las de inferencia tienen ámbitos separados
- El punto final
GET /auth/management-keys/validationpermite probar tu configuración - Todos los puntos finales de gestión se organizan en torno al
teamId