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

API de gestión: gestión de claves y facturación

Lección 12 de 14 Actualizado el 28 de julio de 2026 Intermedio
En esta página
  1. Gestiona tu cuenta sin la consola
  2. Aprovisionamiento y rotación de claves
  3. Seguimiento y control de la facturación
  4. Monitoriza tu consumo con la granularidad adecuada
  5. Puntos clave

Gestiona tu cuenta sin la consola

La API de gestión de xAI es una interfaz REST dedicada a la administración de tu cuenta empresarial. Mientras que la API de inferencia (api.x.ai) invoca modelos, la API de gestión (management-api.x.ai) administra tus recursos. La distinción puede parecer menor, pero no lo es. Cualquier operación que de otro modo exigiría que alguien abriera la consola web y hiciera clic se vuelve aquí automatizable: trazable, reproducible e integrable con las herramientas que tus equipos ya utilizan.

Aprovisionamiento y rotación de claves

Crear claves mediante la API te permite automatizar el aprovisionamiento para una nueva aplicación o entorno:

curl -X POST "https://management-api.x.ai/auth/teams/{teamId}/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cle-production-chatbot",
    "acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
    "qps": 10,
    "qpm": 100,
    "tpm": 1000000,
    "expireTime": "2026-12-31T23:59:59Z"
  }'

Los parámetros de esta solicitud definen por completo el alcance de la clave:

  • name: Identificador legible para humanos de la clave
  • acls: Lista de permisos (puntos finales y modelos autorizados)
  • qps/qpm/tpm: Límites de tasa por segundo, por minuto y tokens por minuto
  • expireTime: Fecha de caducidad automática

Establecer expireTime en el momento de la creación es el hábito que más problemas te ahorrará a largo plazo: una clave emitida para un piloto de tres meses caduca por sí sola, en lugar de permanecer indefinidamente en un archivo de configuración que nadie vuelve a leer.

La rotación periódica de claves sigue la misma higiene de seguridad. El punto final dedicado genera una nueva clave secreta e invalida la anterior:

curl -X POST "https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

Advertencia: la antigua clave secreta se invalida inmediata y permanentemente. Prepárate para desplegar el nuevo valor en tu gestor de secretos antes de ejecutar el comando, nunca después. Tres puntos finales de solo lectura completan el conjunto: GET /auth/teams/{teamId}/api-keys enumera todas las claves del equipo, GET /auth/api-keys/{apiKeyId}/propagation verifica que la clave se ha propagado en todos los nodos, y GET /auth/teams/{teamId}/models lista los modelos accesibles con sus precios. El segundo es el que debes consultar justo después de una rotación, cuando una aplicación sigue devolviendo errores de autenticación y no estás seguro de si se trata de un error de la aplicación o simplemente de un retraso en la propagación.

Seguimiento y control de la facturación

La recuperación de información de facturación utiliza un punto final dedicado:

curl "https://management-api.x.ai/v1/billing/teams/{teamId}/billing-info" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

Puedes recuperar el historial de facturas con filtrado por periodo, aquí para marzo de 2026:

curl "https://management-api.x.ai/v1/billing/teams/{teamId}/invoices?billingCycle.year=2026&billingCycle.month=3" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

Cada factura tiene un estado entre PENDING, PAID, FAILED y WILL_NEVER_BE_CHARGED. Detectar un estado FAILED en tu monitorización es mucho mejor que enterarte del incidente por una interrupción del servicio un lunes por la mañana.

Para evitar desviaciones presupuestarias, configura un límite mensual:

curl -X POST "https://management-api.x.ai/v1/billing/teams/{teamId}/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthlyLimit": 5000}'

Si operas en modalidad de prepago, comprueba el saldo de la misma manera:

# Comprobar saldo
curl "https://management-api.x.ai/v1/billing/teams/{teamId}/prepaid/balance" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

Recuerda que los créditos de prepago son no reembolsables, salvo obligación legal. Dimensiona tus compras en función del consumo observado durante varias semanas, no de proyecciones de crecimiento optimistas.

Monitoriza tu consumo con la granularidad adecuada

El punto final de analíticas te permite seguir el uso con gran fineza:

curl -X POST "https://management-api.x.ai/v1/billing/teams/{teamId}/usage" \
  -H "Authorization: Bearer $MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "analyticsRequest": {
      "timeRange": {
        "startTime": "2026-03-01 00:00:00",
        "endTime": "2026-04-01 00:00:00",
        "timezone": "UTC"
      },
      "timeUnit": "DAY",
      "values": [{"name": "tokens", "aggregation": "SUM"}],
      "groupBy": ["model"]
    }
  }'

Esta solicitud devuelve el consumo diario de tokens, desglosado por modelo, para el mes de marzo. Al cambiar timeUnit, pasas de una vista mensual a una por minuto: los valores posibles son MONTH, CALENDAR_WEEK, DAY, HOUR, QUARTER_HOUR y MINUTE. Las agregaciones van mucho más allá de los totales simples, con SUM, AVG, MIN, MAX, P50, P90, P99 y COUNT. Los percentiles caracterizan la carga de forma eficaz porque los promedios suavizan precisamente los picos que determinan la capacidad que realmente necesitas.

La API de gestión ocupa entonces su lugar en tu cadena de herramientas. Aprovisionas claves desde Terraform o Pulumi igual que una base de datos, tu canal de CI/CD crea claves efímeras para entornos de prueba y las elimina al finalizar la ejecución, los scripts de monitorización lanzan alertas antes de alcanzar el límite de gasto y tus cuadros de mando internos muestran el consumo sin que un humano tenga que exportar un CSV cada lunes.

Puntos clave

  • La API de gestión en management-api.x.ai gestiona claves, facturación y métricas
  • La rotación de claves invalida permanentemente la clave secreta anterior
  • Los límites de gasto protegen contra desviaciones presupuestarias
  • Las analíticas de uso ofrecen granularidad desde el minuto hasta el mes
  • Integra la API de gestión en tus herramientas de infraestructura para automatizar la administración