API de gestion

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

{
  "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"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

Vue d’ensemble

La Management API vous permet de récupérer les totaux de solde d’organisation, de gérer les API Keys d’organisation et de récupérer l’usage et la facturation d’une clé donnée sans utiliser de clé d’inférence standard. Utilisez un jeton de gestion depuis la page Paramètres de votre tableau de bord :

Authorization: Bearer mt-your-management-token

Les management tokens sont différents des API Keys d’inférence. Utilisez mt-... pour /v1/management/* et sk-... pour les endpoints de modèle comme /v1/responses.

Endpoints disponibles

Point de terminaison	Méthode	Description
`/v1/management/balance`	GET	Récupère les totaux de solde actuels de l’organisation
`/v1/management/api-keys`	GET	Liste les API Keys gérées par l’utilisateur dans l’organisation courante
`/v1/management/api-keys`	POST	Crée une nouvelle API Key utilisateur
`/v1/management/api-keys/{keyId}`	PATCH	Met à jour le nom, la limite d’usage, les modèles autorisés, l’expiration ou le statut
`/v1/management/api-keys/{keyId}/usage`	GET	Récupère les détails d’usage paginés pour une clé donnée
`/v1/management/api-keys/{keyId}/billing`	GET	Récupère les ventilations de facturation agrégées pour une clé donnée

Contrat des filtres d’usage

GET /v1/management/api-keys/{keyId}/usage prend en charge les paramètres de requête suivants :

Paramètre	Type	Valeurs par défaut / limites	Description
`page`	integer	défaut `1`, min. `1`	Numéro de page basé sur 1
`limit`	integer	défaut `50`, min. `1`, max. `100`	Taille de page
`model`	string	longueur max. `100`	Nom du modèle demandé
`modelVendor`	string	longueur max. `100`	Fournisseur public du modèle
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	Borne inférieure incluse ; accepte RFC3339 avec fuseau horaire ou `YYYY-MM-DD`
`endDate`	string	-	Borne supérieure incluse ; accepte RFC3339 avec fuseau horaire ou `YYYY-MM-DD`

Si startDate et endDate sont présents ensemble, startDate doit être inférieur ou égal à endDate.

Contrat du body API Key

POST /v1/management/api-keys

Champ	Type	Valeurs par défaut / limites	Description
`name`	string	requis, valeur par défaut `Default Key`, longueur `1-50`	Nom affiché ; les espaces de début et de fin sont retirés côté serveur
`limitAmount`	number \| null	min. `0`, entrée max. `1000000`	`null` ou omis = illimité, `0` = quota nul. Les valeurs positives sont normalisées vers un plafond stocké qui ne peut pas dépasser l’équivalent de `100000` USD.
`limitCurrency`	enum	valeur par défaut `USD`	USD uniquement. L’envoi de `CNY` renvoie `400 currency_retired`.
`models`	string[]	valeur par défaut `[]`	Liste d’autorisation optionnelle des modèles logiques
`expiresAt`	string \| null	datetime RFC3339	`null` signifie sans date d’expiration

PATCH /v1/management/api-keys/

Champ	Type	Valeurs par défaut / limites	Description
`status`	enum	-	`active`, `inactive`, `revoked`
`name`	string	longueur `1-50`	Nom affiché mis à jour
`limitAmount`	number \| null	min. `0`, entrée max. `1000000`	`null` = illimité, `0` = quota nul. Les valeurs positives sont normalisées vers un plafond stocké qui ne peut pas dépasser l’équivalent de `100000` USD.
`limitCurrency`	enum	valeur par défaut `USD`	USD uniquement. L’envoi de `CNY` renvoie `400 currency_retired`.
`models`	string[]	-	Liste d’autorisation des modèles logiques mise à jour
`expiresAt`	string \| null	datetime RFC3339	`null` efface la date d’expiration

Au moins un champ doit être fourni dans la requête PATCH.

Champs monétaires

Les champs monétaires des requêtes et réponses de l’API de gestion prennent uniquement en charge l’USD.
limitCurrency vaut USD par défaut ; l’envoi de CNY renvoie 400 currency_retired.

Sémantique des rapports

model désigne le modèle public demandé par l’appelant.
modelVendor désigne le fournisseur public du modèle, et non la route physique cachée.
scene correspond à la scène publique de la requête, dérivée de l’endpoint ou du type de tâche.

Les réponses n’exposent que des champs publics de facturation et de reporting. Les détails de routage interne et les métadonnées physiques restent masqués.

Les lignes /usage peuvent inclure billing_transaction_id une fois que la requête sous-jacente est réglée. Utilisez request_id + billing_transaction_id pour le rapprochement au niveau de la requête.

Note sur la pagination de la facturation

/usage est paginé. /billing est actuellement un endpoint de synthèse agrégée et ne renvoie pas de métadonnées de pagination de type page / limit. Pour des enregistrements ligne à ligne, utilisez /usage.

Exemple rapide

Commencez par consulter le solde de l’organisation avec le jeton de gestion courant :

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

Listez ensuite les API Keys disponibles pour ce même jeton de gestion :

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

{
  "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"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

Essentiel

Texte

Fichiers & lots

Images

Audio & temps réel

Musique

Vidéo & ressources

Worlds

3D

Tâches asynchrones

Gemini natif

Gestion

Vue d’ensemble

Endpoints disponibles

Contrat des filtres d’usage

Contrat du body API Key

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

Champs monétaires

Sémantique des rapports

Exemple rapide

Étapes suivantes

​Vue d’ensemble

​Endpoints disponibles

​Contrat des filtres d’usage

​Contrat du body API Key

​POST /v1/management/api-keys

​PATCH /v1/management/api-keys/

​Champs monétaires

​Sémantique des rapports

​Note sur la pagination de la facturation

​Exemple rapide

​Étapes suivantes

Vue d’ensemble

Endpoints disponibles

Contrat des filtres d’usage

Contrat du body API Key

POST /v1/management/api-keys

PATCH /v1/management/api-keys/

Champs monétaires

Sémantique des rapports

Note sur la pagination de la facturation

Exemple rapide

Étapes suivantes