> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 余额查询

> 查询账号或 API 密钥的余额与用量

## 接口信息

| 项目 | 说明 |
| - | - |
| 服务域名 | `https://maas.gravitex.ai/prod-api` |
| 数据格式 | `application/json` |
| 字符编码 | `UTF-8` |
| 协议 | `HTTPS`（强制） |
| 金额币种 | `USD`（美元） |

此接口没有请求参数，只需携带认证头。

## 1. 认证

所有请求都必须在 HTTP Header 中携带 Bearer 凭证。**支持两种凭证，任选其一**：

| 凭证类型 | 获取位置 | 查询范围 |
| - | - | - |
| 系统访问令牌（Access Token） | 控制台「个人设置 → 系统访问令牌」 | 整个账号 |
| API 密钥（API Key） | 控制台「令牌管理」，通常以 `sk-` 开头 | 仅这把密钥 |

| 字段 | 必填 | 说明 |
| - | - | - |
| `Authorization` | 是 | 格式为 `Bearer <凭证>`，填入上述任一凭证即可 |

```http theme={null}
# 方式一：系统访问令牌
Authorization: Bearer <access_token>

# 方式二：API 密钥
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
```

以下情况视为认证失败：凭证缺失或错误、凭证已删除或禁用、账号已禁用。

***

## 2. 通用响应结构

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": { }
}
```

| 字段 | 类型 | 说明 |
| - | - | - |
| `code` | integer | 业务状态码，`200` 表示成功 |
| `msg` | string | 提示信息 |
| `data` | object | 业务数据；失败时为 `null` |

### 业务状态码

| code | 说明 |
| - | - |
| 200 | 成功 |
| 401 | 认证失败（凭证缺失、无效或已禁用） |

> 请以响应体中的 `code` 判断请求是否成功。

### 金额格式

* 所有金额都以\*\*美元（USD）\*\*表示，类型为 **string**，避免浮点精度丢失。
* 余额类金额**固定保留 4 位小数**，例如 `"986.9275"`。
* 模型单价**按实际价格输出，不补末尾的 0**，例如 `"40"`、`"2.5"`、`"0.00075"`。

***

## 3. 余额查询

```
GET /api/account/balance
```

根据凭证类型返回不同结构，可以用 `data.type` 区分。

### 3.1 使用系统访问令牌：返回账号余额（`type = account`）

| 字段 | 类型 | 说明 |
| - | - | - |
| `type` | string | 固定为 `account` |
| `username` | string | 账号名 |
| `group` | string | 账号分组 |
| `currency` | string | 固定为 `USD` |
| `balance` | string | 剩余金额 |
| `usedAmount` | string | 已用金额 |
| `totalAmount` | string | 总金额（剩余 + 已用） |

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "type": "account",
    "username": "demo_user",
    "group": "default",
    "currency": "USD",
    "balance": "986.9275",
    "usedAmount": "213.0725",
    "totalAmount": "1200.0000"
  }
}
```

> 企业子账号只返回该子账号自己的余额，不包含企业其他成员。

### 3.2 使用 API 密钥：返回该密钥的额度（`type = token`）

| 字段 | 类型 | 说明 |
| - | - | - |
| `type` | string | 固定为 `token` |
| `tokenName` | string | 密钥名称 |
| `group` | string | 密钥分组；为空表示跟随账号分组 |
| `unlimited` | boolean | 是否不限额度 |
| `currency` | string | 固定为 `USD` |
| `balance` | string | 该密钥剩余可用金额 |
| `usedAmount` | string | 该密钥已用金额 |
| `totalAmount` | string | 该密钥总额度（剩余 + 已用） |
| `expiresAt` | integer | 过期时间（秒级时间戳），`0` 表示永不过期 |
| `modelLimitsEnabled` | boolean | 是否开启了模型限制 |
| `modelLimits` | string\[] | 该密钥允许调用的模型；未开启限制时为空数组 |

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "type": "token",
    "tokenName": "my-key",
    "group": "",
    "unlimited": false,
    "currency": "USD",
    "balance": "100.0000",
    "usedAmount": "50.0000",
    "totalAmount": "150.0000",
    "expiresAt": 0,
    "modelLimitsEnabled": false,
    "modelLimits": []
  }
}
```

> 不限额度的密钥（`unlimited = true`）不受密钥额度约束，`balance` 可能显示为负数，这种情况请以 `usedAmount` 作为该密钥的用量参考，实际可用金额以账号余额为准。

***

## 4. 调用示例

```bash theme={null}
# 使用系统访问令牌查询账号余额
curl -s "https://maas.gravitex.ai/prod-api/api/account/balance" \
  -H "Authorization: Bearer <access_token>"

# 使用 API 密钥查询该密钥的额度
curl -s "https://maas.gravitex.ai/prod-api/api/account/balance" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx"
```

***

## 5. 注意事项

1. **数据刷新**：余额数据最长约 1 分钟刷新一次，充值或消费后可能稍有延迟。
2. **以实际扣费为准**：本接口用于查询和预估，最终费用请以账单为准。
3. **妥善保管凭证**：系统访问令牌可以查询整个账号的信息，请勿泄露；如果只需要查询某个密钥的额度，建议使用对应的 API 密钥调用。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.