TokenLab Management API ergänzt Workspace-Guthabenabfrage

Es lässt sich vermeiden, dass eine automatisierte Produktionspipeline aufgrund eines leeren Guthabens stillsteht. Die TokenLab Management API Guthabenabfrage bietet automatisierten Workflows einen abfragbaren Guthabenbetrag unter Verwendung eines Management-Tokens anstelle eines Inferenz-Schlüssels.

Diese Anleitung behandelt den Endpunkt-Vertrag von GET /v1/management/balance, Authentifizierungsanforderungen, den Umgang mit Währungen und wie sich Antwortschemata direkt anhand der offiziellen Dokumentation verifizieren lassen.

Wichtigste Erkenntnisse

• Der Management API Guthaben-Endpunkt (GET /v1/management/balance) gibt das aktuelle Workspace-Guthaben, die gesamten Aufladungen und die kumulierten Nutzungsausgaben zurück.
• Die Authentifizierung erfordert ein Management-Token (mt-...), das in Dashboard → API → Management Tokens erstellt wird, wodurch operative Überprüfungen von Modell-Inferenz-Schlüsseln (sk-...) getrennt bleiben.
• Alle monetären Werte werden in USD zurückgegeben. Exakte Berechnungen sollten die zurückgegebenen Dezimal-Strings verwenden (balance_decimal, total_recharge_decimal, total_used_decimal).
• Der Endpunkt lässt sich mit Berichten auf Schlüssel-Ebene wie /v1/management/api-keys/{keyId}/usage und /v1/management/api-keys/{keyId}/billing kombinieren.

Management-Tokens vs. Modell-Inferenz-API-Schlüssel

Management-Tokens und Modell-Inferenz-Schlüssel erfüllen in TokenLab unterschiedliche operative Rollen:

• Modell-Inferenz-API-Schlüssel (sk-...): Werden verwendet, um Inferenz-Endpunkte wie POST /v1/chat/completions, POST /v1/responses, native Anthropic Messages unter POST /v1/messages und Gemini unter /v1beta/models/... aufzurufen. Diese Schlüssel führen Generierungsanfragen aus, legen jedoch keine Finanzdaten auf Organisationsebene offen.
• Management-Tokens (mt-...): Beschränkt auf /v1/management/*-Routen. Sie ermöglichen es Backends, Workspace-Guthaben einzusehen, API-Schlüssel aufzulisten oder zu bearbeiten und die Nutzung zu überwachen, ohne Zugriff auf Modellgenerierungen zu gewähren.

Die Trennung dieser Zugangsdaten stellt sicher, dass Buchhaltungs-Skripte und Finanz-Monitore keine abrechenbaren Inferenzaufrufe auslösen können, während Modell-Worker niemals Zugriff auf die Kontoadministration erhalten.

Der Wire-Vertrag des Guthaben-Endpunkts

Senden Sie eine GET-Anfrage an https://api.tokenlab.sh/v1/management/balance und authentifizieren Sie sich mit Ihrem Management-Token im Authorization-Header:

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

Antwortschema

Eine erfolgreiche Anfrage gibt 200 OK mit einem organization_balance-Objekt zurück:

{
  "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"
}

Antwortfelder

• object (string): Immer organization_balance.
• organization_id (string): Organisation, die dem aktuellen Management-Token zugeordnet ist.
• balance (number): Aktuelles Workspace-Guthaben in USD als Gleitkommazahl zur Anzeige.
• balance_decimal (string): Exaktes aktuelles Workspace-Guthaben in USD, formatiert als Dezimal-String für den Finanzabgleich.
• total_recharge (number): Gesamter erfolgreicher Workspace-Aufladebetrag in USD.
• total_recharge_decimal (string): Exakter gesamter erfolgreicher Workspace-Aufladebetrag in USD, formatiert als Dezimal-String.
• total_used (number): Gesamte Workspace-Nutzungsausgaben in USD.
• total_used_decimal (string): Exakte gesamte Workspace-Nutzungsausgaben in USD, formatiert als Dezimal-String.

Monetäre Felder sind strikt USD. Wenn Sie das Guthaben programmatisch für Schwellenwertprüfungen oder den Hauptbuchabgleich parsen, parsen Sie balance_decimal mit einer Bibliothek für beliebige Dezimalpräzision statt mit Gleitkomma-Primitiven, um Präzisionsverluste zu vermeiden.

Implementierung von Guthabenprüfungen

Typische Integrationsmuster umfassen:

1. Pre-Batch Guardrails: Vor dem Absenden großer Workloads – wie etwa umfangreicher Generierungen mit Modellen wie gpt-5.5 oder glm-5.2 – fragen Sie /v1/management/balance ab. Wenn balance_decimal unter die geschätzten Batch-Kosten fällt, pausieren Sie die Job-Warteschlange.
2. Benachrichtigungen bei niedrigem Guthaben: Während automatisierte E-Mail-Benachrichtigungen unter Konsole → Einstellungen konfiguriert werden können, kann ein geplanter Monitoring-Cron den Endpunkt abfragen und interne Benachrichtigungen über Slack, PagerDuty oder Webhooks auslösen.
3. Abrechnungsabgleich: Kombinieren Sie das Live-Workspace-Guthaben mit den Nutzungsdatensätzen einzelner Schlüssel (/v1/management/api-keys/{keyId}/usage), um Token-Ausgaben mit abgerechneten Rechnungspositionen abzugleichen.

Die vollständigen Endpunktspezifikationen und Methoden zur Schlüsselverwaltung finden Sie in der API-Referenz zum Abrufen des Workspace-Guthabens und in der Übersicht zur Management API.