管理
管理 API
查询工作区余额、管理 API 密钥,并获取用量和账单
管理 API 适合在自己的后台或自动化程序中管理 TokenLab 工作区。它使用管理令牌,不需要把普通 API 密钥交给管理程序。
在 Dashboard → API → Management Tokens 创建管理令牌:
Authorization: Bearer mt-your-management-token管理令牌与 API 密钥用途不同。mt-... 只能调用 /v1/management/*;sk-... 用于 /v1/responses 等模型接口。
可用接口
| 接口 | 方法 | 用途 |
|---|---|---|
/v1/management/balance | GET | 获取工作区余额 |
/v1/management/api-keys | GET | 列出 API 密钥 |
/v1/management/api-keys | POST | 创建 API 密钥 |
/v1/management/api-keys/{keyId} | PATCH | 修改名称、额度、模型范围、过期时间或状态 |
/v1/management/api-keys/{keyId}/usage | GET | 获取逐条用量记录 |
/v1/management/api-keys/{keyId}/billing | GET | 获取汇总账单 |
API 密钥
- 新密钥的完整值只在创建响应中出现一次。
models: []表示不增加密钥级模型限制。limitAmount: null表示不限额,0表示不能产生费用。- 金额只支持 USD;传入
CNY会返回400 currency_retired。 inactive可重新启用;revoked用于永久停用。
用量与账单
/usage 返回分页后的逐条记录,可以按模型、模型厂商、场景和日期筛选。完成结算的记录会带有 billing_transaction_id;需要将扣费与请求对应时,请与 request_id 一起保存。
/billing 返回按模型、模型厂商、场景和日期分组的汇总,不包含工作区充值和发票。
只有日期的 endDate(如 2026-07-31)表示当天 UTC 00:00。要包含整天,请传下一天的日期,或传 2026-07-31T23:59:59Z 这样的 RFC3339 时间。
错误
错误使用标准的 error 对象,按状态码和 code 处理。
| 状态码 | code | 含义 |
|---|---|---|
| 400 | validation_error | 字段或查询参数不合法 |
| 400 | invalid_model_access | models 中有模型不被工作区的模型策略允许 |
| 400 | currency_retired | limitCurrency 为 CNY,请改用 USD |
| 401 | invalid_management_token | 令牌缺失、格式不对或已撤销 |
| 403 | organization_inactive | 工作区未启用 |
| 404 | not_found | 这把 API 密钥不在当前工作区 |
| 409 | api_key_revoked | 已撤销的密钥不能再启用,请创建新密钥 |
| 429 | report_busy | 同时运行的用量或账单报表过多,按 Retry-After 的秒数后重试 |
示例
curl "https://api.tokenlab.sh/v1/management/balance" \
-H "Authorization: Bearer mt-your-management-token"