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

# 查询用户余额

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

# 查询用户余额

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

## 使用场景

> **控制台展示**
>
> 在你的应用控制台中展示实时账户余额

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

> **充值提醒**
>
> 在积分用完前提示用户充值

> **用量追踪**
>
> 监控积分消耗并追踪消费模式

## 重要说明

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

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


## OpenAPI

````yaml zh/api-manual/account-management/user-balance.json GET /api/user/balance
openapi: 3.0.0
info:
  title: PoYo AI - 用户余额 API
  description: 实时查询用户账户的积分余额
  version: 1.0.0
servers:
  - url: https://api.poyo.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: support@poyo.ai
                  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: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
        data:
          type: object
          required:
            - email
            - credits_amount
          properties:
            email:
              type: string
              format: email
              example: support@poyo.ai
              description: 账户关联的邮箱地址
            credits_amount:
              type: integer
              example: 17276
              description: 账户当前的积分余额
    ErrorResponse:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: integer
          example: 400
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
        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：登录 PoYo，进入 **仪表盘 → API
        密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建
        Key。


        在请求头中添加：


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

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