Verwaltung
Management-API
Verwalten Sie Organisationsguthaben, API-Keys sowie Nutzungs- und Abrechnungsdaten pro Key mit einem Management-Token.
Überblick
Mit der Management API können Sie Organisationsguthaben abrufen, Organisations-API-Keys verwalten und Nutzung sowie Billing für einen bestimmten Key abrufen, ohne einen normalen Inference-API-Key zu verwenden.
Erstellen Sie ein Management-Token unter Dashboard → API → Management Tokens:
Authorization: Bearer mt-your-management-tokenManagement-Tokens sind nicht dasselbe wie Inference-API-Keys. Verwenden Sie mt-... für /v1/management/* und sk-... für Modell-Inference-Endpunkte wie /v1/responses.
Verfügbare Endpunkte
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/v1/management/balance | GET | Ruft aktuelle Guthabensummen der Organisation ab |
/v1/management/api-keys | GET | Listet benutzerverwaltete API-Keys in der aktuellen Organisation auf |
/v1/management/api-keys | POST | Erstellt einen neuen Benutzer-API-Key |
/v1/management/api-keys/{keyId} | PATCH | Aktualisiert Name, Nutzungslimit, erlaubte Modelle, Ablaufzeit oder Status |
/v1/management/api-keys/{keyId}/usage | GET | Ruft paginierte Nutzungsdetails für einen bestimmten Key ab |
/v1/management/api-keys/{keyId}/billing | GET | Ruft aggregierte Billing-Aufschlüsselungen für einen bestimmten Key ab |
Nutzungsfilter
GET /v1/management/api-keys/{keyId}/usage unterstützt die folgenden Query-Parameter:
| Parameter | Typ | Standard / Grenzen | Beschreibung |
|---|---|---|---|
page | integer | Standard 1, min. 1 | Seitennummer ab 1 |
limit | integer | Standard 50, min. 1, max. 100 | Seitengröße |
model | string | max. Länge 100 | Angeforderter Modellname |
modelVendor | string | max. Länge 100 | Öffentlicher Modellanbieter |
scene | enum | - | chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime |
startDate | string | - | Inklusive Untergrenze; akzeptiert RFC3339 mit Zeitzone oder YYYY-MM-DD |
endDate | string | - | Inklusive Obergrenze; akzeptiert RFC3339 mit Zeitzone oder YYYY-MM-DD |
Wenn startDate und endDate zusammen angegeben werden, muss startDate kleiner oder gleich endDate sein.
API-Key-Anfragekörper
POST /v1/management/api-keys
| Feld | Typ | Standard / Grenzen | Beschreibung |
|---|---|---|---|
name | string | optional, Standard Default Key, Länge 1-50 | Anzeigename; führende und nachgestellte Leerzeichen werden serverseitig entfernt |
limitAmount | number | string | null | 0–100000 USD | null bedeutet unbegrenzt; 0 verhindert Ausgaben. Dezimalstrings erlauben bis zu 6 Nachkommastellen. Bei der Erstellung bedeutet das Weglassen unbegrenzt. |
limitCurrency | enum | Standardwert USD | Nur USD. Das Senden von CNY gibt 400 currency_retired zurück. |
models | string[] | Standard [] | Optionale Modell-Allowlist |
deliveryPolicy | string | null | auto, verified, official, null | null übernimmt die Zustellrichtlinie des Workspace. |
expiresAt | string | null | RFC3339-Datetime | null bedeutet ohne Ablaufzeit |
PATCH /v1/management/api-keys/{keyId}
| Feld | Typ | Standard / Grenzen | Beschreibung |
|---|---|---|---|
status | enum | - | active, inactive, revoked |
name | string | Länge 1-50 | Aktualisierter Anzeigename |
limitAmount | number | string | null | 0–100000 USD | null bedeutet unbegrenzt; 0 verhindert Ausgaben. Dezimalstrings erlauben bis zu 6 Nachkommastellen. |
limitCurrency | enum | Standardwert USD | Nur USD. Das Senden von CNY gibt 400 currency_retired zurück. Bei Angabe ist auch limitAmount erforderlich. |
models | string[] | - | Aktualisierte Modell-Allowlist |
deliveryPolicy | string | null | auto, verified, official, null | null übernimmt die Zustellrichtlinie des Workspace. |
expiresAt | string | null | RFC3339-Datetime | null entfernt die Ablaufzeit |
Mindestens ein PATCH-Feld muss angegeben werden.
Geldbetragsfelder
- Geldbetragsfelder in Anfragen und Antworten der Management API unterstützen ausschließlich USD.
limitCurrencyist standardmäßigUSD; beiCNYwird400 currency_retiredzurückgegeben.
Reporting-Semantik
modelbezeichnet den vom Aufrufer angeforderten Modellnamen.modelVendorbezeichnet den öffentlichen Modellanbieter, nicht interne Ausführungsdetails.sceneist die öffentliche Request-Szene, die aus Endpoint oder Task-Typ abgeleitet wird.
Die Antworten geben nur öffentliche Billing- und Reporting-Felder zurück. Provider-Ausführungsdetails bleiben verborgen.
- Einzelne
/usage-Zeilen könnenbilling_transaction_identhalten, sobald die zugrunde liegende Anfrage den abgerechneten Zustand erreicht hat. Verwenden Sierequest_id+billing_transaction_idfür den Abgleich auf Anfrageebene.
Hinweis zur Abrechnungspaginierung
/usage ist paginiert. /billing ist derzeit ein aggregierter Breakdown-Endpunkt und liefert keine page / limit-Paginierungsmetadaten. Wenn Sie Einzelzeilen benötigen, verwenden Sie /usage.
Schnellbeispiel
Prüfen Sie zunächst das Organisationsguthaben mit dem aktuellen Management-Token:
Anfrage
curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"Listen Sie danach die API-Keys auf, die demselben Management-Token zur Verfügung stehen:
Anfrage
curl "https://api.tokenlab.sh/v1/management/api-keys" \
-H "Authorization: Bearer mt-your-management-token"Antwort
{
"object": "list",
"data": [
{
"id": "key_abc123def456",
"name": "Backend Worker",
"key_prefix": "sk-abc123...",
"status": "active",
"limit_amount": 500.0,
"limit_amount_decimal": "500",
"used_amount": 148.25,
"used_amount_decimal": "148.25",
"models": [
"gpt-4o-mini",
"claude-3-7-sonnet"
],
"expires_at": "2026-04-30T00:00:00.000Z",
"last_used_at": "2026-03-27T08:12:45.000Z",
"created_at": "2026-03-01T10:00:00.000Z",
"delivery_policy": null
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1,
"totalPages": 1
}
}