TokenLab Management API 新增工作区余额查询功能

自动化生产流水线因余额不足而停滞是完全可以避免的。TokenLab Management API 余额查询功能支持通过管理令牌（而非推理密钥）为自动化工作流提供可查询的余额总计。

本指南涵盖 GET /v1/management/balance 端点契约、身份验证要求、货币处理方式，以及如何直接对照官方文档验证响应结构。

核心要点

• Management API 余额端点（GET /v1/management/balance）返回当前工作区余额、充值总额以及累计使用消费。
• 身份验证需要使用在 Dashboard → API → Management Tokens 中创建的管理令牌（mt-...），从而将运维检查与模型推理密钥（sk-...）隔离开来。
• 所有金额数值均以 USD 返回。高精度计算应使用返回的十进制字符串（balance_decimal、total_recharge_decimal、total_used_decimal）。
• 该端点可与密钥级报告（如 /v1/management/api-keys/{keyId}/usage 和 /v1/management/api-keys/{keyId}/billing）配合使用。

管理令牌对比模型推理 API 密钥

管理令牌和模型推理密钥在 TokenLab 中扮演着不同的运维角色：

• 模型推理 API 密钥 (sk-...)：用于调用推理端点，例如 POST /v1/chat/completions、POST /v1/responses、POST /v1/messages 上的原生 Anthropic Messages 以及 /v1beta/models/... 上的 Gemini。这些密钥负责执行生成请求，但不会暴露组织层面的财务数据。
• 管理令牌 (mt-...)：仅限于 /v1/management/* 路由。它们允许后端检查工作区余额、列出或编辑 API 密钥以及监控用量，而不会赋予模型生成权限。

将这些凭证分开可确保记账脚本和财务监控程序不会触发计费的推理调用，同时模型工作节点也绝不会获得账户管理权限。

余额端点传输契约

向 https://api.tokenlab.sh/v1/management/balance 发送 GET 请求，并在 Authorization 请求头中使用您的管理令牌进行身份验证：

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

响应结构

成功的请求将返回 200 OK 及一个 organization_balance 对象：

{
  "object": "organization_balance",
  "organization_id": "org_123",
  "balance": 42.5,
  "balance_decimal": "42.50",
  "total_recharge": 100,
  "total_recharge_decimal": "100",
  "total_used": 57.5,
  "total_used_decimal": "57.50"
}

响应字段

• object (string)：固定为 organization_balance。
• organization_id (string)：与当前管理令牌关联的组织。
• balance (number)：当前工作区余额（USD），采用浮点数表示，用于展示。
• balance_decimal (string)：当前工作区精确余额（USD），格式化为十进制字符串，用于财务对账。
• total_recharge (number)：工作区充值成功的总金额（USD）。
• total_recharge_decimal (string)：工作区充值成功的精确总金额（USD），格式化为十进制字符串。
• total_used (number)：工作区累计使用消费总额（USD）。
• total_used_decimal (string)：工作区累计使用消费的精确总额（USD），格式化为十进制字符串。

金额字段严格以 USD 为单位。在以编程方式解析余额以进行阈值检查或分类账对账时，请使用任意精度十进制库解析 balance_decimal，而非使用浮点原始类型，以避免精度丢失。

实现余额检查

常见的集成模式包括：

1. 批处理前防护检查：在分发大型工作负载之前（例如在 gpt-5.5 或 glm-5.2 等模型上进行大批量生成），先查询 /v1/management/balance。如果 balance_decimal 低于预估的批处理成本，则暂停作业队列。
2. 低余额预警：虽然可以在 Console → Settings 中配置自动邮件通知，但也可以通过定时监控任务轮询该端点，并触发内部 Slack、PagerDuty 或 Webhook 通知。
3. 账单对账：将实时工作区余额与单个密钥的使用记录（/v1/management/api-keys/{keyId}/usage）相结合，根据已结算的账单明细核对 Token 支出。

有关完整的端点规范和密钥管理方法，请参阅获取工作区余额 API 参考和 Management API 概述。