餘額查詢

回傳目前 API Key 所屬帳戶的餘額狀態，包含可用餘額、歷史累計入帳與累計扣費。

本介面屬於 OfoxAI OpenAPI，與具體協議（OpenAI / Anthropic / Gemini）無關。任意一個有效的 OfoxAI API Key 皆可呼叫，回應結構與 cc-switch 等第三方工具相容。

端點


GET https://api.ofox.io/v1/user/balance

同一介面也透過 Anthropic / Gemini 入口暴露，方便已配置不同 Base URL 的用戶端複用：

URL
`https://api.ofox.io/v1/user/balance`
`https://api.ofox.io/anthropic/user/balance`
`https://api.ofox.io/gemini/user/balance`

三個 URL 回傳完全一致的回應結構。

認證

使用任一有效的 OfoxAI API Key（sk-...），透過 Authorization: Bearer 標頭傳入：


Authorization: Bearer sk-xxx

請使用使用者級 API Key（在 Dashboard 建立），不要使用 Internal / Gateway 內部金鑰。

請求範例

cURL

Terminal


curl https://api.ofox.io/v1/user/balance \
  -H "Authorization: Bearer $OFOX_API_KEY"

Python

balance.py


import os
import requests
 
resp = requests.get(
    "https://api.ofox.io/v1/user/balance",
    headers={"Authorization": f"Bearer {os.environ['OFOX_API_KEY']}"},
)
data = resp.json()
print(f"可用餘額: ${data['balance']:.4f} {data['currency']}")

TypeScript

balance.ts


const resp = await fetch('https://api.ofox.io/v1/user/balance', {
  headers: { Authorization: `Bearer ${process.env.OFOX_API_KEY}` },
})
const data = await resp.json()
console.log(`可用餘額: $${data.balance.toFixed(4)} ${data.currency}`)

回應格式

成功回應 200 OK：


{
  "is_active": true,
  "balance": 42.1357,
  "total": 100.0000,
  "used": 57.8643,
  "currency": "USD"
}

回應欄位

欄位	類型	說明
`is_active`	boolean	帳戶是否可用。鑑權通過即回傳 `true`；鑑權失敗時回傳 `false`
`balance`	number	當前可用餘額，等於 `total - used`
`total`	number	歷史累計入帳：充值 + 贈送 + 禮品卡總和
`used`	number	歷史累計扣費：所有呼叫產生的總消耗
`currency`	string	貨幣單位，固定為 `"USD"`

所有金額以美元（USD）為單位，使用 64 位元浮點數表示，底層精度為 NanoDollar（10⁻⁹ USD），可精確到亞美分級別。

錯誤回應

鑑權失敗或服務異常時回傳非 200 狀態碼，回應主體格式與 cc-switch 相容：


{
  "error": "unauthenticated",
  "is_active": false
}

狀態碼	`error` 值	說明
`401`	`unauthenticated`	API Key 無效、已停用或過期
`500`	`internal error`	服務內部錯誤，請稍後重試

第三方工具相容性

本介面的回應結構與 cc-switch 餘額查詢範本相容，可直接作為 cc-switch 的餘額提供方接入：

is_active 用於狀態檢查
balance 對應 cc-switch 的 remaining 欄位
total / used 用於消耗進度顯示