> ## 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 的调用额度（与账户积分独立）。

查询当前 API Key 的**调用额度**（与账户积分余额独立）。若在控制台为该 Key 设置了 `total_quota`，则按额度限制；未设置时视为不限额。

### 响应字段

| 字段 | 类型 | 说明 |
| :- | :- | :- |
| `name` | string | Key 名称 |
| `total_quota` | number | 总额度；`0` 表示不限额 |
| `used_quota` | number | 已用额度（见下方说明） |
| `available_quota` | number | 剩余额度 = `total_quota` - `used_quota`；不限额时为 `0` |
| `unlimited` | boolean | 是否不限额 |

### `used_quota` 说明

`used_quota` 表示**当前这把 API Key** 已累计消耗的调用额度，单位与 `total_quota` 一致（积分）。

* **统计范围**：仅包含通过**本 Key** 发起、且已成功扣费的 OpenAPI 调用，不含同账户下其他 Key。
* **累加时机**：任务提交成功并完成扣费时，将该次任务的 `cost` 累加到 `used_quota`。
* **额度校验**：当 `total_quota > 0` 且 `used_quota >= total_quota` 时，该 Key 将无法继续发起新的计费请求。
* **与账户 `used_coin` 的区别**：[`/user/balance`](/zh/api-reference/common/user-balance) 中的 `used_coin` 是**用户账户**维度的历史净消费；`used_quota` 是**单 Key** 维度的额度计数。

<Note>
  实际扣费仍从用户积分账户余额中扣除；`total_quota` / `used_quota` 仅用于限制单 Key 的最大可消费额度，不单独充值。
</Note>

### 示例

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

```json theme={null}
{
  "code": 20000,
  "msg": "ok",
  "data": {
    "name": "production-key",
    "total_quota": 1000,
    "used_quota": 120.5,
    "available_quota": 879.5,
    "unlimited": false
  }
}
```


## OpenAPI

````yaml GET /v1/key/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/key/balance:
    get:
      tags:
        - Account
      summary: Get API key quota balance
      description: >-
        Returns call quota for the current API key (independent of account
        points).
      operationId: getKeyBalance
      responses:
        '200':
          description: Key quota
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyBalanceResponse'
components:
  schemas:
    KeyBalanceResponse:
      type: object
      properties:
        code:
          type: integer
          example: 20000
        msg:
          type: string
        data:
          type: object
          properties:
            name:
              type: string
            total_quota:
              type: number
            used_quota:
              type: number
            available_quota:
              type: number
            unlimited:
              type: boolean
  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.