# 余额查询 — OfoxAI OpenAPI

Source: https://ofox.io/zh/docs/api/openapi/balance

返回当前 API Key 所属账户的余额状态，包含可用余额、历史累计入账与累计扣费。

本接口属于 **OfoxAI OpenAPI**，与具体协议（OpenAI / Anthropic / Gemini）无关。任意一个有效的 OfoxAI API Key 均可调用，响应结构与 cc-switch 等第三方工具兼容。

## 端点

```http
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` 头传入：

```http
Authorization: Bearer sk-xxx
```

请使用用户级 API Key（在 [Dashboard](https://app.ofox.io/manage/api-keys) 创建），不要使用 Internal / Gateway 内部密钥。

## 请求示例

**cURL**

```bash filename="Terminal"
curl https://api.ofox.io/v1/user/balance \
  -H "Authorization: Bearer $OFOX_API_KEY"
```

**Python**

```python filename="balance.py" showLineNumbers
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**

```typescript filename="balance.ts" showLineNumbers
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`：

```json
{
  "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 兼容：

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

| 状态码 | `error` 值 | 说明 |
|--------|-----------|------|
| `401` | `unauthenticated` | API Key 无效、已禁用或过期 |
| `500` | `internal error` | 服务内部错误，请稍后重试 |

## 第三方工具兼容性

本接口的响应结构与 [cc-switch](https://github.com/farion1231/cc-switch) 余额查询模板兼容，可直接作为 cc-switch 的余额提供方接入：

- `is_active` 用于状态校验
- `balance` 对应 cc-switch 的 `remaining` 字段
- `total` / `used` 用于消耗进度展示