Manajemen
API Manajemen
Kelola saldo organisasi, API key, serta usage dan billing per key dengan management token.
Ikhtisar
Management API memungkinkan Anda mengambil total saldo organisasi, mengelola API key organisasi, serta mengambil usage dan billing untuk key tertentu tanpa memakai inference API key biasa.
Buat token manajemen di Dashboard → API → Management Tokens:
Authorization: Bearer mt-your-management-tokenManagement token berbeda dari inference API key. Gunakan mt-... untuk /v1/management/*, dan gunakan sk-... untuk endpoint inferensi seperti /v1/responses.
Endpoint Tersedia
| Endpoint | Metode | Deskripsi |
|---|---|---|
/v1/management/balance | GET | Ambil total saldo organisasi saat ini |
/v1/management/api-keys | GET | Daftar API key yang dikelola user di organisasi saat ini |
/v1/management/api-keys | POST | Buat API key user baru |
/v1/management/api-keys/{keyId} | PATCH | Perbarui nama, batas penggunaan, model yang diizinkan, masa berlaku, atau status |
/v1/management/api-keys/{keyId}/usage | GET | Ambil detail usage berpaginasi untuk key tertentu |
/v1/management/api-keys/{keyId}/billing | GET | Ambil breakdown billing teragregasi untuk key tertentu |
Kontrak Filter Usage
GET /v1/management/api-keys/{keyId}/usage mendukung parameter query berikut:
| Parameter | Tipe | Default / Batas | Catatan |
|---|---|---|---|
page | integer | bawaan 1, minimum 1 | Nomor halaman mulai dari 1 |
limit | integer | bawaan 50, minimum 1, maksimum 100 | Ukuran halaman |
model | string | panjang maks 100 | Nama model yang diminta |
modelVendor | string | panjang maks 100 | Vendor model publik |
scene | enum | - | chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime |
startDate | string | - | Batas bawah inklusif; menerima RFC3339 dengan timezone atau YYYY-MM-DD |
endDate | string | - | Batas atas inklusif; menerima RFC3339 dengan timezone atau YYYY-MM-DD |
Jika startDate dan endDate sama-sama ada, startDate harus lebih kecil dari atau sama dengan endDate.
Kontrak Body API Key
POST /v1/management/api-keys
| Bidang | Tipe | Default / Batas | Catatan |
|---|---|---|---|
name | string | opsional, bawaan Default Key, panjang 1-50 | Nama tampilan, dipangkas di sisi server |
limitAmount | number | string | null | 0–100000 USD | null berarti tanpa batas; 0 mencegah pengeluaran. String desimal mendukung hingga 6 angka desimal. Saat membuat kunci, menghilangkan kolom ini berarti tanpa batas. |
limitCurrency | enum | bawaan USD | Hanya USD. Mengirim CNY menghasilkan 400 currency_retired. |
models | string[] | bawaan [] | Daftar izin model opsional |
deliveryPolicy | string | null | auto, verified, official, null | null mewarisi kebijakan pengiriman ruang kerja. |
expiresAt | string | null | datetime RFC3339 | null berarti tidak kedaluwarsa |
PATCH /v1/management/api-keys/{keyId}
| Bidang | Tipe | Default / Batas | Catatan |
|---|---|---|---|
status | enum | - | active, inactive, revoked |
name | string | panjang 1-50 | Nama tampilan yang diperbarui |
limitAmount | number | string | null | 0–100000 USD | null berarti tanpa batas; 0 mencegah pengeluaran. String desimal mendukung hingga 6 angka desimal. |
limitCurrency | enum | bawaan USD | Hanya USD. Mengirim CNY menghasilkan 400 currency_retired. Jika diisi, limitAmount juga wajib disertakan. |
models | string[] | - | Daftar izin model yang diperbarui |
deliveryPolicy | string | null | auto, verified, official, null | null mewarisi kebijakan pengiriman ruang kerja. |
expiresAt | string | null | datetime RFC3339 | null menghapus masa kedaluwarsa |
Setidaknya satu field PATCH harus diberikan.
Kolom moneter
- Kolom moneter dalam permintaan dan respons API Manajemen hanya mendukung USD.
limitCurrencymenggunakanUSDsecara default; mengirimCNYakan mengembalikan400 currency_retired.
Semantik Pelaporan
modelmerujuk ke model publik yang diminta caller.modelVendormerujuk ke vendor model publik, bukan rute penyedia di balik layar.sceneadalah scene request publik yang diturunkan dari endpoint atau jenis tugas.
Respons hanya menampilkan field billing dan reporting publik. Detail routing penyedia tidak ditampilkan.
- Item
/usagedapat menyertakanbilling_transaction_idsetelah request dasar mencapai status billing yang telah diselesaikan. Gunakanrequest_id+billing_transaction_iduntuk rekonsiliasi level request.
Catatan paginasi penagihan
/usage dipaginasi. /billing saat ini adalah endpoint breakdown teragregasi dan tidak mengembalikan metadata paginasi seperti page / limit. Jika Anda butuh record level baris, gunakan /usage.
Contoh Singkat
Mulailah dengan memeriksa saldo organisasi menggunakan management token saat ini:
Permintaan
curl -X GET "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"Lalu tampilkan API key yang tersedia untuk management token yang sama:
Permintaan
curl "https://api.tokenlab.sh/v1/management/api-keys" \
-H "Authorization: Bearer mt-your-management-token"Respons
{
"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
}
}