L'API Management de TokenLab ajoute la consultation du solde de l'espace de travail

Laisser un pipeline de production automatisé s'interrompre en raison d'un solde épuisé est pourtant évitable. La consultation du solde via l'API Management de TokenLab permet aux flux de travail automatisés d'interroger le solde total à l'aide d'un token de gestion plutôt que d'une clé d'inférence.

Ce guide couvre le contrat de l'endpoint GET /v1/management/balance, les exigences d'authentification, la gestion des devises et la manière de vérifier les schémas de réponse directement par rapport à la documentation officielle.

Points clés

• L'endpoint de solde de l'API Management (GET /v1/management/balance) renvoie le solde actuel de l'espace de travail, le montant total des recharges et les dépenses d'utilisation cumulées.
• L'authentification nécessite un token de gestion (mt-...) créé dans Dashboard → API → Management Tokens, séparant ainsi les vérifications opérationnelles des clés d'inférence de modèles (sk-...).
• Toutes les valeurs monétaires sont renvoyées en USD. Les calculs exacts doivent s'appuyer sur les chaînes décimales retournées (balance_decimal, total_recharge_decimal, total_used_decimal).
• Cet endpoint s'associe aux rapports au niveau des clés tels que /v1/management/api-keys/{keyId}/usage et /v1/management/api-keys/{keyId}/billing.

Tokens de gestion vs clés d'API d'inférence de modèles

Les tokens de gestion et les clés d'API d'inférence de modèles remplissent des rôles opérationnels distincts dans TokenLab :

• Clés d'API d'inférence de modèles (sk-...) : utilisées pour appeler des endpoints d'inférence tels que POST /v1/chat/completions, POST /v1/responses, les messages Anthropic natifs sur POST /v1/messages et Gemini sur /v1beta/models/.... Ces clés exécutent des requêtes de génération, mais n'exposent pas les données financières au niveau de l'organisation.
• Tokens de gestion (mt-...) : limités aux routes /v1/management/*. Ils permettent aux backends d'inspecter le solde de l'espace de travail, de lister ou modifier les clés d'API et de surveiller l'utilisation sans accorder d'accès à la génération de modèles.

La séparation de ces identifiants garantit que les scripts comptables et les outils de suivi financier ne peuvent pas déclencher d'appels d'inférence facturables, tandis que les workers exécutant les modèles n'ont jamais accès à l'administration du compte.

Contrat réseau de l'endpoint de solde

Envoyez une requête GET à https://api.tokenlab.sh/v1/management/balance en vous authentifiant avec votre token de gestion dans l'en-tête Authorization :

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

Schéma de réponse

Une requête réussie renvoie 200 OK avec un objet 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"
}

Champs de la réponse

• object (string) : toujours organization_balance.
• organization_id (string) : organisation associée au token de gestion actuel.
• balance (number) : solde actuel de l'espace de travail en USD sous forme de nombre à virgule flottante pour l'affichage.
• balance_decimal (string) : solde actuel exact de l'espace de travail en USD formaté en chaîne décimale pour le rapprochement financier.
• total_recharge (number) : montant total des recharges de l'espace de travail ayant abouti, en USD.
• total_recharge_decimal (string) : montant total exact des recharges de l'espace de travail ayant abouti, en USD et formaté en chaîne décimale.
• total_used (number) : dépenses totales d'utilisation de l'espace de travail en USD.
• total_used_decimal (string) : dépenses totales exactes d'utilisation de l'espace de travail en USD formatées en chaîne décimale.

Les champs monétaires sont strictement en USD. Lors de l'analyse programmatique du solde pour des contrôles de seuil ou le rapprochement comptable, traitez balance_decimal avec une bibliothèque décimale à précision arbitraire plutôt qu'avec des types primitifs à virgule flottante afin d'éviter toute perte de précision.

Mise en œuvre des vérifications de solde

Les modèles d'intégration courants comprennent :

1. Garde-fous avant traitement par lots : avant de lancer d'importantes charges de travail — telles que des générations en grand volume sur des modèles comme gpt-5.5 ou glm-5.2 — interrogez /v1/management/balance. Si balance_decimal passe sous le coût estimé du lot, mettez en pause la file d'attente des tâches.
2. Alertes de solde bas : bien que des notifications automatisées par e-mail puissent être configurées dans Console → Settings, une tâche cron de surveillance planifiée peut interroger régulièrement l'endpoint et déclencher des notifications internes sur Slack, PagerDuty ou par webhook.
3. Rapprochement de facturation : combinez le solde en direct de l'espace de travail avec les enregistrements d'utilisation des clés individuelles (/v1/management/api-keys/{keyId}/usage) afin de rapprocher les dépenses de tokens des lignes de facturation réglées.

Pour obtenir les spécifications complètes des points de terminaison et les méthodes de gestion des clés, consultez la Référence de l'API Get Workspace Balance et la Présentation de l'API Management.