查詢餘額與額度
查詢這把密鑰此刻還能花多少,以及它的額度;不計費,不要求餘額為正。
/v1/usagebalance 是這把密鑰此刻還能花的額度:密鑰沒設額度即帳戶餘額,設了額度即密鑰剩餘額度;團隊成員與部門的密鑰還會再按本期剩餘額度封頂。設了額度的密鑰仍從帳戶餘額扣費——帳戶餘額先用完時,即使 balance 還有額度,請求也會回傳 402。
金額以美元計價(2026-10-01 起 ledger_currency 為 "USD",與 unit 一致):balance、remaining 和不帶後綴的 quota.* 都是美元金額;需要人民幣時讀 _cny 欄位(對應 _usd 金額的人民幣金額,固定換算,不是即時匯率)。本端點只認 Authorization: Bearer,且不使用標準錯誤結構:請以 is_active 判斷,不要只看 HTTP 狀態碼。
非同步任務查詢在任務結束後的根物件 usage 裡帶單任務扣費:美元金額 cost_usd、人民幣金額 cost 與 cost 的幣種 currency,任務列表裡每個終態任務的 usage 也帶這些欄位(上文的 _cny / _usd 雙幣欄位只屬於本介面),見扣費。
請求標頭
Bearer sk-…:主控台「API 密鑰」中建立的密鑰,所屬分組須包含請求的模型
回傳
200餘額與額度;密鑰過期或成員停用時也是 200,is_active: false
balance 大於 0 時為 true
這把密鑰此刻還能花的額度(美元)
與 balance 相同
恆為 "USD",與 ledger_currency 一致
不帶後綴金額的幣種,為 "USD"(2026-10-01 之前為 "CNY")
balance 的人民幣金額
balance 的美元金額
密鑰額度
與 balance 相同
密鑰剩餘額度;沒設額度時等於帳戶餘額
密鑰額度;0 表示沒設額度
這把密鑰累計已扣費金額
密鑰沒設額度時為 true
人民幣
美元
沒設額度時為 null
沒設額度時為 null
沒設額度時為 null
沒設額度時為 null
人民幣
美元
僅異常時:api key expired、member disabled 等
這把密鑰所屬的分組;專屬分組不回傳此欄位
分組 ID
分組名稱
各語言的分組名稱,鍵為語言程式碼(如 en、zh-tw、es、ja),與主控台顯示一致
分組的協定族,例如 openai、claude、gemini
錯誤
sk- 開頭:missing or invalid api key;密鑰不存在或已停用:invalid api key