La Management API de TokenLab añade la consulta de saldo del espacio de trabajo

Dejar que un pipeline de producción automatizado se detenga por falta de saldo es algo evitable. La consulta de saldo de la Management API de TokenLab proporciona a los flujos de trabajo automatizados un total de saldo consultable mediante un token de gestión en lugar de una clave de inferencia.

Esta guía cubre el contrato del endpoint GET /v1/management/balance, los requisitos de autenticación, la gestión de divisas y cómo verificar los esquemas de respuesta directamente contra la documentación oficial.

Puntos clave

• El endpoint de saldo de la Management API (GET /v1/management/balance) devuelve el saldo actual del espacio de trabajo, el total de recargas y el gasto de uso acumulado.
• La autenticación requiere un token de gestión (mt-...) creado en Dashboard → API → Management Tokens, lo que mantiene las comprobaciones operativas separadas de las claves de inferencia de modelos (sk-...).
• Todos los valores monetarios se devuelven en USD. Los cálculos exactos deben utilizar las cadenas decimales devueltas (balance_decimal, total_recharge_decimal, total_used_decimal).
• El endpoint se combina con informes a nivel de clave como /v1/management/api-keys/{keyId}/usage y /v1/management/api-keys/{keyId}/billing.

Tokens de gestión frente a claves API de inferencia de modelos

Los tokens de gestión y las claves de inferencia de modelos cumplen funciones operativas distintas en TokenLab:

• Claves API de inferencia de modelos (sk-...): Se utilizan para llamar a endpoints de inferencia como POST /v1/chat/completions, POST /v1/responses, Messages nativo de Anthropic en POST /v1/messages y Gemini en /v1beta/models/.... Estas claves ejecutan solicitudes de generación, pero no exponen datos financieros a nivel de organización.
• Tokens de gestión (mt-...): Restringidos a las rutas /v1/management/*. Permiten que los backends inspeccionen saldos del espacio de trabajo, listen o editen claves API y supervisen el uso sin otorgar acceso de generación de modelos.

Separar estas credenciales garantiza que los scripts de contabilidad y los monitores financieros no puedan desencadenar llamadas de inferencia facturables, al tiempo que los workers de modelos nunca obtienen acceso a la administración de la cuenta.

El contrato de red del endpoint de saldo

Envía una solicitud GET a https://api.tokenlab.sh/v1/management/balance autenticándote con tu token de gestión en la cabecera Authorization:

curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
  -H "Authorization: Bearer mt-your-management-token"

Esquema de respuesta

Una solicitud correcta devuelve 200 OK con un objeto organization_balance:

{
  "object": "organization_balance",
  "organization_id": "org_123",
  "balance": 42.5,
  "balance_decimal": "42.50",
  "total_recharge": 100,
  "total_recharge_decimal": "100",
  "total_used": 57.5,
  "total_used_decimal": "57.50"
}

Campos de respuesta

• object (string): Siempre organization_balance.
• organization_id (string): Organización asociada al token de gestión actual.
• balance (number): Saldo actual del espacio de trabajo en USD como número de coma flotante para su visualización.
• balance_decimal (string): Saldo actual exacto del espacio de trabajo en USD formateado como cadena decimal para conciliación financiera.
• total_recharge (number): Importe total de recargas satisfactorias del espacio de trabajo en USD.
• total_recharge_decimal (string): Importe total exacto de recargas satisfactorias del espacio de trabajo en USD formateado como cadena decimal.
• total_used (number): Gasto total de uso del espacio de trabajo en USD.
• total_used_decimal (string): Gasto total exacto de uso del espacio de trabajo en USD formateado como cadena decimal.

Los campos monetarios están estrictamente en USD. Al analizar el saldo de manera programática para comprobaciones de límites o conciliación contable, procesa balance_decimal con una librería decimal de precisión arbitraria en lugar de tipos primitivos de coma flotante para evitar la pérdida de precisión.

Implementación de comprobaciones de saldo

Los patrones de integración comunes incluyen:

1. Protecciones previas a lotes (Pre-Batch Guardrails): Antes de enviar cargas de trabajo grandes, como la generación de alto volumen en modelos como gpt-5.5 o glm-5.2, consulta /v1/management/balance. Si balance_decimal cae por debajo del coste estimado del lote, pausa la cola de tareas.
2. Alertas de saldo bajo: Aunque se pueden configurar notificaciones automáticas por correo electrónico en Console → Settings, un cron de monitorización programado puede sondear el endpoint y activar notificaciones internas en Slack, PagerDuty o webhooks.
3. Conciliación de facturación: Combina el saldo en tiempo real del espacio de trabajo con los registros de uso de claves individuales (/v1/management/api-keys/{keyId}/usage) para conciliar el gasto de tokens con las líneas de factura liquidadas.

Para obtener las especificaciones completas de los endpoints y los métodos de gestión de claves, consulta la Referencia de la API de obtención del saldo del espacio de trabajo y la Introducción a la Management API.