管理
管理 API
查看 Workspace 餘額、管理 API key,以及擷取用量與帳單資訊
從您自己的後端或自動化程式使用 Management API 來管理 TokenLab Workspace。它使用 management token,因此程式不需要一般的 API key。
在 控制台 → API → Management Tokens 建立 management token:
Authorization: Bearer mt-your-management-tokenManagement token 與 API key 具有不同的角色。僅將 mt-... 用於 /v1/management/*。模型 API(例如 /v1/responses)請使用 sk-...。
端點
| 端點 | 方法 | 用途 |
|---|---|---|
/v1/management/balance | GET | 取得 Workspace 餘額 |
/v1/management/api-keys | GET | 列出 API key |
/v1/management/api-keys | POST | 建立 API key |
/v1/management/api-keys/{keyId} | PATCH | 修改其名稱、額度上限、模型、過期時間或狀態 |
/v1/management/api-keys/{keyId}/usage | GET | 取得個別用量記錄 |
/v1/management/api-keys/{keyId}/billing | GET | 取得帳單摘要 |
API Key
- 新 key 的完整密鑰僅會在建立時的回應中顯示。
models: []不會新增任何 key 層級的模型限制。limitAmount: null表示無限制。0則可防止該 key 產生費用。- 金額單位為 USD。傳送
CNY會傳回400 currency_retired。 inactive可以再次啟用。若要永久停用 key,請使用revoked。
用量與帳單
/usage 會傳回分頁記錄,並支援模型、模型製造商、場景與日期篩選條件。已結算的記錄可包含 billing_transaction_id;當您需要將扣款與請求進行對帳時,請將其與 request_id 一併儲存。
/billing 會傳回依模型、模型製造商、場景與日期分組的總計資訊。它不包含 Workspace 加值或發票。
僅指定日期的 endDate(例如 2026-07-31)表示該日開始的 00:00 UTC。若要包含整天,請傳入下一天的日期,或使用 RFC3339 時間格式(例如 2026-07-31T23:59:59Z)。
錯誤
錯誤會使用標準的 error 物件。請根據狀態碼與 code 進行處理。
| 狀態 | code | 說明 |
|---|---|---|
| 400 | validation_error | 欄位或查詢參數無效 |
| 400 | invalid_model_access | models 中的某個模型不符合 Workspace 的模型政策規定 |
| 400 | currency_retired | limitCurrency 為 CNY;請使用 USD |
| 401 | invalid_management_token | token 遺失、格式錯誤或已被撤銷 |
| 403 | organization_inactive | 該 Workspace 未處於啟用狀態 |
| 404 | not_found | 此 Workspace 中不存在該 API key |
| 409 | api_key_revoked | 已撤銷的 key 無法再次啟用;請建立新的 key |
| 429 | report_busy | 正在執行的用量或帳單報表過多。請在 Retry-After 秒後重試 |
範例
curl "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"