Gestion
API de gestion
Gérez le solde d’organisation, les API Keys, ainsi que l’usage et la facturation par clé avec un jeton de gestion.
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.
Créez un jeton de gestion dans Dashboard → API → Management Tokens :
Authorization: Bearer mt-your-management-tokenLes 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 | facultatif, 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 | string | null | 0–100000 USD | null signifie sans limite ; 0 empêche toute dépense. Les chaînes décimales acceptent jusqu’à 6 décimales. À la création, omettre ce champ signifie sans limite. |
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 |
deliveryPolicy | string | null | auto, verified, official, null | null hérite de la politique de livraison de l’espace de travail. |
expiresAt | string | null | datetime RFC3339 | null signifie sans date d’expiration |
PATCH /v1/management/api-keys/{keyId}
| Champ | Type | Valeurs par défaut / limites | Description |
|---|---|---|---|
status | enum | - | active, inactive, revoked |
name | string | longueur 1-50 | Nom affiché mis à jour |
limitAmount | number | string | null | 0–100000 USD | null signifie sans limite ; 0 empêche toute dépense. Les chaînes décimales acceptent jusqu’à 6 décimales. |
limitCurrency | enum | valeur par défaut USD | USD uniquement. L'envoi de CNY renvoie 400 currency_retired. Si ce champ est fourni, limitAmount est obligatoire. |
models | string[] | - | Liste d’autorisation des modèles logiques mise à jour |
deliveryPolicy | string | null | auto, verified, official, null | null hérite de la politique de livraison de l’espace de travail. |
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.
limitCurrencyvautUSDpar défaut ; l’envoi deCNYrenvoie400 currency_retired.
Sémantique des rapports
modeldésigne le modèle public demandé par l’appelant.modelVendordésigne le fournisseur public du modèle, et non la route physique cachée.scenecorrespond à 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
/usagepeuvent inclurebilling_transaction_idune fois que la requête sous-jacente est réglée. Utilisezrequest_id+billing_transaction_idpour 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 :
Requête
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 :
Requête
curl "https://api.tokenlab.sh/v1/management/api-keys" \
-H "Authorization: Bearer mt-your-management-token"Réponse
{
"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
}
}