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

# 查询用户余额

> 查询你的用户账户积分余额

实时查询你的用户账户当前积分余额。

## 使用场景

> [card] 仪表盘展示
>
> 在你的应用仪表盘中展示实时账户余额

> [card] 余额提醒
>
> 积分低于阈值时发送通知

> [card] 充值提醒
>
> 在积分用完前提示用户充值

> [card] 用量追踪
>
> 监控积分消耗并追踪消费模式

## 注意事项

> [!NOTE]
>
> **实时余额**：返回的余额反映请求时刻的当前积分数量。

> [!TIP]
>
> **频率控制**：避免过度轮询。缓存余额，仅在必要时刷新（例如完成一个生成任务之后）。

> [!WARNING]
>
> **积分扣除**：只有生成任务成功完成时才会扣除积分。失败的任务不消耗积分。


## OpenAPI

````yaml zh/api-manual/account-management/user-balance.json GET /api/user/balance
openapi: 3.0.0
info:
  title: Vidgo API - 用户余额 API
  description: 实时查询用户账户的积分余额
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: 生产环境
security:
  - BearerAuth: []
paths:
  /api/user/balance:
    get:
      tags:
        - Account Management
      summary: 查询用户余额
      description: 实时查询用户账户当前的积分余额
      operationId: getUserBalance
      responses:
        '200':
          description: 余额获取成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
              example:
                code: 200
                data:
                  email: goseasp@gmail.com
                  credits_amount: 17276
        '401':
          description: 未授权 - API Key 无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 401
                error:
                  message: Invalid API key
                  type: authentication_error
        '429':
          description: 请求过多 - 超出速率限制
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 429
                error:
                  message: Rate limit exceeded
                  type: rate_limit_error
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 500
                error:
                  message: Internal server error
                  type: server_error
components:
  schemas:
    BalanceResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          description: HTTP 状态码
        data:
          type: object
          required:
            - email
            - credits_amount
          properties:
            email:
              type: string
              format: email
              example: goseasp@gmail.com
              description: 账户关联的邮箱地址
            credits_amount:
              type: integer
              example: 17276
              description: 账户当前的积分余额
    ErrorResponse:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: integer
          example: 400
          description: HTTP 状态码
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              example: Invalid API key
              description: 描述错误原因的错误信息
            type:
              type: string
              example: authentication_error
              description: 错误类型标识
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证


        获取 API Key：


        进入 **仪表盘 → API 密钥**（[API Key
        管理页面](https://vidgo.ai/apis/dashboard/api-key)）获取 API Key


        在请求头中添加：


        ```

        Authorization: Bearer VIDGO_API_KEY

        ```

````

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