跳转到主要内容

​
APIYI 余额查询接口文档

​
接口概述

APIYI 余额查询接口用于获取当前账户的额度使用情况，包括总配额、已使用额度、剩余额度和请求次数等信息。 这个接口，可帮助客户以简单的方式获取 账号余额，以便可更主动、自由的控制余额告警~

​
如何获取 Authorization ？

访问 https://api.apiyi.com/account/profile 最下方有一个账号选项 - 系统令牌 输入当前的账户密码后，会得到一个 AccessToken，该密钥可用于后续接口的查询数据。 images/apiyi-system-accesstoken.png

​
接口信息

项目说明
接口URLhttps://api.apiyi.com/api/user/self
请求方法GET
认证方式Authorization Header
响应格式JSON

​
请求说明

​
请求Headers

Header名称必填说明
Authorization是API访问令牌，格式：直接填写token字符串
Accept否建议设置为 application/json
Content-Type否建议设置为 application/json

​
请求参数

该接口为GET请求，不需要传递任何请求体（body）参数。

​
响应说明

​
成功响应示例

{
  "success": true,
  "message": null,
  "data": {
    "id": 19489,
    "username": "testnano",
    "display_name": "testnano",
    "role": 1,
    "status": 1,
    "email": "",
    "quota": 24997909,
    "used_quota": 10027091,
    "request_count": 339,
    "group": "ceshi",
    "aff_code": "ZM0H",
    "inviter_id": 0,
    "access_token": "...",
    "ModelFixedPrice": [...]
  }
}

​
核心响应字段说明

字段名类型说明
successBoolean请求是否成功
messageString错误信息（成功时为null）
data.usernameString用户名
data.display_nameString显示名称
data.quotaInteger剩余额度（当前可用余额，单位：额度）
data.used_quotaInteger已使用额度（单位：额度）
data.request_countInteger总请求次数
data.groupString用户所属组
data.ModelFixedPriceArray模型价格列表（可忽略）

​
额度换算说明

500,000 额度 = 1.00 美金 (USD)
计算公式：
  • 美金金额 = 额度 ÷ 500,000
  • 剩余额度 = quota（quota 本身就是当前剩余余额）
  • 剩余美金 = quota ÷ 500,000
示例：
  • quota: 24997909 → $49.99 USD（当前剩余余额）
  • used_quota: 10027091 → $20.05 USD（已使用）

​
错误响应

​
HTTP 401 - 认证失败

{
  "success": false,
  "message": "Unauthorized"
}
原因： Authorization令牌无效或已过期 解决方法： 检查并更新API令牌

​
HTTP 403 - 权限不足

{
  "success": false,
  "message": "Forbidden"
}
原因： 当前令牌无权访问该接口 解决方法： 联系管理员确认权限配置

​
代码示例

​
cURL 示例

curl --compressed 'https://api.apiyi.com/api/user/self' \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_TOKEN_HERE' \
  -H 'Content-Type: application/json'
重要提示： 必须添加 --compressed 选项，因为API返回的是gzip压缩内容，否则会得到乱码。
快速测试（替换YOUR_TOKEN_HERE）： 
export APIYI_TOKEN='YOUR_TOKEN_HERE'

curl --compressed -s 'https://api.apiyi.com/api/user/self' \
  -H 'Accept: application/json' \
  -H "Authorization: $APIYI_TOKEN" \
  -H 'Content-Type: application/json' | \
  jq '.data | {quota, used_quota, request_count}'
说明：-s 选项隐藏进度条，--compressed 自动解压gzip响应

​
Python 示例（基础版）

import requests

# 配置
url = "https://api.apiyi.com/api/user/self"
authorization = "YOUR_TOKEN_HERE"  # 替换为你的令牌

# 请求头
headers = {
    'Accept': 'application/json',
    'Authorization': authorization,
    'Content-Type': 'application/json'
}

# 发送请求
response = requests.get(url, headers=headers, timeout=10)

# 检查响应
if response.status_code == 200:
    data = response.json()
    user_data = data['data']

    # 提取核心信息
    quota = user_data['quota']
    used_quota = user_data['used_quota']
    request_count = user_data['request_count']

    # 计算美金金额
    # 注意：quota 就是当前剩余余额
    remaining_usd = quota / 500000
    used_usd = used_quota / 500000

    # 打印结果
    print(f"剩余额度：${remaining_usd:.2f} USD ({quota:,} 额度)")
    print(f"已使用：${used_usd:.2f} USD ({used_quota:,} 额度)")
    print(f"请求次数：{request_count:,} 次")
else:
    print(f"请求失败：HTTP {response.status_code}")
    print(response.text)

​
Python 示例（完整优化版）

我们提供了完整的优化版脚本 quota_optimized.py，包含以下特性：
  • ✅ 完整的错误处理
  • ✅ 环境变量支持（安全管理令牌）
  • ✅ 格式化输出
  • ✅ 自动美金换算
  • ✅ 超时控制
  • ✅ 面向对象设计
使用方法： 
# 方式1：使用环境变量（推荐）
export APIYI_TOKEN='YOUR_TOKEN_HERE'
python quota_optimized.py

# 方式2：命令行参数
python quota_optimized.py 'YOUR_TOKEN_HERE'
输出示例： 
============================================================
📊 APIYI 账户余额信息
============================================================
用户名称：testnano (testnano)
------------------------------------------------------------
剩余额度：24,997,909 额度 ($49.99 USD)
已使用：  10,027,091 额度 ($20.05 USD)
请求次数：339 次
============================================================
💡 换算说明：500,000 额度 = $1.00 USD
============================================================

​
常见问题

​
Q1: 如何获取Authorization令牌？

请参考《APIYI认证说明文档》（由管理员单独提供）。

​
Q2: 查询余额是否会消耗配额？

否，查询账户余额接口不会消耗您的配额额度。

​
Q3: 多久可以查询一次余额？

建议查询间隔不少于1秒，避免频繁请求触发限流。

​
Q4: ModelFixedPrice 字段有什么用？

该字段返回各个AI模型的定价信息。如果您只关心余额信息，可以忽略该字段。

​
Q5: quota 字段代表什么？

quota 字段就是当前的剩余额度。如果 quota 为 0 或接近 0，说明账户余额不足，需要及时充值。

​
Q6: curl命令返回乱码或jq报错怎么办？

问题： 执行curl命令时得到乱码，或者jq报错 “Invalid numeric literal” 原因： API返回的是gzip压缩内容（Content-Encoding: gzip），curl没有自动解压。 解决方案： 添加 --compressed 选项让curl自动解压： 
# ✅ 正确（带 --compressed）
curl --compressed 'https://api.apiyi.com/api/user/self' \
  -H 'Authorization: YOUR_TOKEN' | jq

# ❌ 错误（缺少 --compressed）
curl 'https://api.apiyi.com/api/user/self' \
  -H 'Authorization: YOUR_TOKEN' | jq

​
注意事项

  1. 安全性
    • 切勿在代码中硬编码Authorization令牌
    • 建议使用环境变量或配置文件管理敏感信息
    • 不要将包含令牌的代码提交到公开仓库
  2. 请求限制
    • 建议设置合理的请求超时时间（推荐10秒）
    • 避免过于频繁的查询请求
  3. 异常处理
    • 务必处理网络异常、超时、认证失败等错误情况
    • 建议记录错误日志便于排查问题
  4. 响应格式
    • API返回gzip压缩内容，使用curl时必须添加 --compressed 选项
    • Python的requests库会自动处理gzip解压，无需额外配置

​
更新日志

版本日期说明
v1.12025-12-28修复curl示例，添加 --compressed 选项解决gzip压缩问题；更新FAQ和注意事项
v1.02025-12-28初始版本，提供余额查询接口文档和优化脚本
技术支持： 如有问题，请联系APIYI技术支持团队