# 余额查询 API

## 概述

余额查询 API 用于查询当前用户的账户余额信息，包括可用余额和冻结余额。

## 接口信息

- **接口路径**: `/api/v2/open/balance`
- **请求方法**: `GET`
- **认证方式**: Bearer Token (API Key)

## 请求参数

### Headers

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| Authorization | string | 是 | Bearer {API_KEY} |

### Query Parameters

无

## 响应格式

### 成功响应

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "user_id": "user_123456",
    "balance": "1000.50",
    "frozen_balance": "50.00",
    "currency": "积分"
  }
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| user_id | string | 用户ID |
| balance | string | 可用余额 |
| frozen_balance | string | 冻结余额 |
| currency | string | 货币单位 |

### 错误响应

```json
{
  "code": 401,
  "msg": "用户ID无效",
  "data": null
}
```

```json
{
  "code": 500,
  "msg": "查询余额失败",
  "data": null
}
```

## 请求示例

### cURL

```bash
curl -X GET "https://api.apiverse.ai/api/v2/open/balance" \
  -H "Authorization: Bearer your_api_key_here"
```

### Python

```python
import requests

url = "https://api.apiverse.ai/api/v2/open/balance"
headers = {
    "Authorization": "Bearer your_api_key_here"
}

response = requests.get(url, headers=headers)
print(response.json())
```

### JavaScript

```javascript
fetch('https://api.apiverse.ai/api/v2/open/balance', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_api_key_here'
  }
})
.then(response => response.json())
.then(data => console.log(data));
```

## 使用场景

1. **余额查询**: 在调用消费类 API 前，先查询账户余额，确保余额充足
2. **余额监控**: 定期查询余额，当余额低于阈值时及时充值
3. **账单核对**: 在任务完成后查询余额变化，核对消费金额

## 注意事项

1. 余额单位为"积分"，具体兑换比例请咨询客服
2. 冻结余额是指已下单但未完成的任务预扣金额
3. 实际可用余额 = 余额 - 冻结余额
4. 如果用户没有余额记录，接口会返回余额为 0
5. 建议在调用消费类 API 前先查询余额，避免余额不足导致任务失败

## 关于大模型（LLM）消费

- 若账户已开通大模型（LLM）能力，本接口返回的余额为账户可用余额合计，已包含大模型可用额度部分。
- 大模型调用的消费在账户余额中结算，本接口返回的余额已计入该部分。
- 大模型的用量与消费明细请前往控制台「用量」/「账单」页面查看，不在本站流水中体现。

## 错误码说明

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 401 | 用户ID无效 | 检查 API Key 是否正确 |
| 500 | 查询余额失败 | 稍后重试或联系技术支持 |