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

# 查询用户账户余额

> 返回当前 API Key 所属用户的积分余额。

查询当前 API Key 所属用户的**积分账户余额**。OpenAPI 调用产生的费用从该账户扣除；创建任务前可先调用本接口确认可用余额是否充足。

余额过低时也可改为接收推送，见 [余额告警 Webhook](/zh/api-reference/common/balance-webhook)。

### 响应字段

| 字段 | 类型 | 说明 |
| :- | :- | :- |
| `balance` | number | 账户累计额度（可用 + 历史净消费） |
| `used_coin` | number | 历史净消费（见下方说明） |
| `available` | number | 可用余额 = `balance` - `used_coin` |

### `used_coin` 说明

`used_coin` 表示**用户账户**维度的历史净消费，单位为积分。

* **计算方式**：账户下全部 `consumption`（消费）记录之和，减去全部 `refund`（退款）记录之和。
* **统计范围**：包含该用户下**所有 API Key** 的扣费，不限于当前请求所用的 Key。
* **与 Key `used_quota` 的区别**：[`/key/balance`](/zh/api-reference/common/key-balance) 中的 `used_quota` 仅统计单 Key 的额度消耗，用于 Key 级上限；`used_coin` 反映整个账户已花出去多少积分。

### 示例

```bash theme={null}
curl -X GET 'https://sigrunai.com/v1/user/balance' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```json theme={null}
{
  "code": 20000,
  "msg": "ok",
  "data": {
    "balance": 100.5,
    "used_coin": 20.3,
    "available": 80.2
  }
}
```


## OpenAPI

````yaml GET /v1/user/balance
openapi: 3.1.0
info:
  title: AI Platform OpenAPI
  description: 异步图片与视频生成。创建后轮询 task_id；结果 URL 约保留 3 天。
  version: 1.0.0
servers:
  - url: https://sigrunai.com
    description: AI Platform 生产环境
security:
  - bearerAuth: []
paths:
  /v1/user/balance:
    get:
      tags:
        - Account
      summary: Get user account balance
      description: Returns points balance for the account that owns the current API key.
      operationId: getUserBalance
      responses:
        '200':
          description: Balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserBalanceResponse'
components:
  schemas:
    UserBalanceResponse:
      type: object
      properties:
        code:
          type: integer
          example: 20000
        msg:
          type: string
        data:
          type: object
          properties:
            balance:
              type: number
            used_coin:
              type: number
            available:
              type: number
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 控制台创建的 API Key，格式：Bearer sk_xxx

````

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