讓自動化生產流程因餘額不足而停擺是可以避免的。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。以程式化方式解析餘額以進行門檻檢查或總帳對帳時，請使用任意精度（arbitrary-precision）小數函式庫來解析 balance_decimal，而非使用浮點數基本型別，以避免精度遺失。
實作餘額檢查
常見的整合模式包括：
- 批次處理前防護措施：在分派大型工作負載前（例如使用 gpt-5.5 或 glm-5.2 等模型進行大量生成），先查詢
/v1/management/balance。若balance_decimal低於預估的批次成本，則暫停工作佇列。 - 低餘額警示：雖然可在 Console → Settings 中設定自動電子郵件通知，但也可以透過排程監控 cron 定期輪詢該端點，並觸發內部 Slack、PagerDuty 或 Webhook 通知。
- 帳務核對：結合即時工作區餘額與個別金鑰的使用紀錄（
/v1/management/api-keys/{keyId}/usage），將 Token 支出與已結算發票明細進行對帳。
如需完整的端點規格與金鑰管理方法，請參閱 取得工作區餘額 API 參考文件 與 Management API 總覽。
