餘額查詢 API

介面概述

餘額查詢介面用於獲取當前賬戶的額度使用情況，包括總配額、已使用額度、剩餘額度和請求次數等資訊。這個介面可幫助客戶以簡單的方式獲取賬號餘額，以便更主動、自由地控制餘額告警。

如何獲取 Authorization

本介面用個人訪問令牌認證（nap_ 開頭），與呼叫模型的 API Key 不是一回事。

打開個人訪問令牌

訪問 api.apiyi.com/account/profile 個人中心，在「賬戶選項」裡點選 個人訪問令牌 → 建立令牌

勾選權限

本介面只需勾選 個人資料 · 讀取。到期時間預設 30 天，建議選久一點

儲存令牌

建立後立即複製儲存，填進請求頭 Authorization

舊系統令牌計劃於 2026-11-11 (UTC+8) 停用。 原來在「賬號選項 - 系統令牌」生成的 AccessToken 在此之前照常可用，之後會返回 401 ACCESS_TOKEN_LEGACY_RETIRED。平臺會視使用情況決定是否延期，建議儘早換成個人訪問令牌：替換請求頭裡的值即可，程式碼不用改。到期時間、IP 白名單與權限的詳細說明見什麼是個人訪問令牌？

介面資訊

專案	說明
介面URL	`https://api.apiyi.com/api/user/self`
請求方法	`GET`
認證方式	Authorization Header（個人訪問令牌，`Bearer` 字首可加可不加）
響應格式	JSON

請求說明

請求 Headers

Header名稱	必填	說明
`Authorization`	是	個人訪問令牌，直接填寫令牌字串
`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": [...]
  }
}

核心響應欄位說明

欄位名	型別	說明
`success`	Boolean	請求是否成功
`message`	String	錯誤資訊（成功時為null）
`data.username`	String	使用者名稱
`data.display_name`	String	顯示名稱
`data.quota`	Integer	剩餘額度（當前可用餘額，單位：額度）
`data.used_quota`	Integer	已使用額度（單位：額度）
`data.request_count`	Integer	總請求次數
`data.group`	String	使用者所屬組
`data.ModelFixedPrice`	Array	模型價格列表（可忽略）

額度換算說明

換算規則

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"
}

原因： 令牌無效、已過期或已刪除。修改密碼、兩步驗證或通行金鑰會撤銷全部個人訪問令牌。 解決方法： 回控制台重新建立個人訪問令牌。另外兩種 401 會帶明確的報文：

報文	原因
`ACCESS_TOKEN_LEGACY_RETIRED`	仍在使用已停用的舊系統令牌，需換成個人訪問令牌
`This access token may not be used from the current IP address.`	請求來源不在令牌的 IP 白名單內；白名單不能修改，需新建令牌

HTTP 403 - 權限不足

{
  "code": "ACCESS_TOKEN_SCOPE_DENIED",
  "message": "This endpoint is outside this access token’s granted permissions.",
  "success": false
}

原因： 個人訪問令牌沒有勾選 個人資料 · 讀取。 解決方法： 新建一把勾選了該權限的令牌（權限建立後不能修改）。

程式碼示例

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.py 即可直接執行：

import os
import sys

import requests

URL = "https://api.apiyi.com/api/user/self"
QUOTA_PER_USD = 500_000


def fetch_quota(token):
    """查詢賬戶餘額，返回 data 欄位。"""
    headers = {
        "Accept": "application/json",
        "Authorization": token,
        "Content-Type": "application/json",
    }
    try:
        resp = requests.get(URL, headers=headers, timeout=10)
    except requests.exceptions.Timeout:
        sys.exit("請求超時，請檢查網路後重試")
    except requests.exceptions.RequestException as exc:
        sys.exit(f"請求失敗：{exc}")

    if resp.status_code == 401:
        sys.exit("認證失敗：令牌無效、已過期或 IP 不在白名單，請回控制台重新建立個人訪問令牌")
    if resp.status_code != 200:
        sys.exit(f"請求失敗：HTTP {resp.status_code}\n{resp.text[:200]}")

    body = resp.json()
    if not body.get("success"):
        sys.exit(f"介面報錯：{body.get('message')}")
    return body["data"]


def report(data):
    quota = data.get("quota", 0)
    used = data.get("used_quota", 0)
    count = data.get("request_count", 0)

    print("=" * 60)
    print("📊 APIYI 賬戶餘額資訊")
    print("=" * 60)
    print(f"使用者名稱稱：{data.get('username')} ({data.get('display_name')})")
    print("-" * 60)
    print(f"剩餘額度：{quota:,} 額度 (${quota / QUOTA_PER_USD:.2f} USD)")
    print(f"已使用：  {used:,} 額度 (${used / QUOTA_PER_USD:.2f} USD)")
    print(f"請求次數：{count:,} 次")
    print("=" * 60)
    print(f"💡 換算說明：{QUOTA_PER_USD:,} 額度 = $1.00 USD")
    print("=" * 60)


if __name__ == "__main__":
    # 優先讀命令列引數，其次讀環境變數，避免把令牌硬編碼進程式碼
    token = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("APIYI_TOKEN")
    if not token:
        sys.exit("請提供令牌：設定環境變數 APIYI_TOKEN，或作為第一個命令列引數傳入")
    report(fetch_quota(token))

使用方法：

# 方式1：使用環境變數（推薦）
export APIYI_TOKEN='YOUR_TOKEN_HERE'
python quota.py

# 方式2：命令列引數
python quota.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
============================================================

常見問題

如何獲取 Authorization 令牌？

請參考上方「如何獲取 Authorization」的步驟，在個人中心建立個人訪問令牌並勾選「個人資料 · 讀取」。舊系統令牌計劃於 2026-11-11 (UTC+8) 停用，詳見什麼是個人訪問令牌？

查詢餘額是否會消耗配額？

否，查詢賬戶餘額介面不會消耗您的配額額度。

多久可以查詢一次餘額？

建議查詢間隔不少於1秒，避免頻繁請求觸發限流。

ModelFixedPrice 欄位有什麼用？

該欄位返回各個AI模型的定價資訊。如果您只關心餘額資訊，可以忽略該欄位。

quota 欄位代表什麼？

quota 欄位就是當前的剩餘額度。如果 quota 為 0 或接近 0，說明賬戶餘額不足，需要及時充值。

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

注意事項

安全性提醒

切勿在程式碼中硬編碼 Authorization 令牌
建議使用環境變數或配置檔案管理敏感資訊
不要將包含令牌的程式碼提交到公開倉庫

請求限制

建議設定合理的請求超時時間（推薦10秒）
避免過於頻繁的查詢請求

異常處理建議

務必處理網路異常、超時、認證失敗等錯誤情況
建議記錄錯誤日誌便於排查問題

響應格式說明

API返回gzip壓縮內容，使用curl時必須新增 --compressed 選項
Python的requests庫會自動處理gzip解壓，無需額外配置

產品基礎

基礎 API

圖片 API（官轉）

影片 API（官轉）

多模態理解 API

文本生成

音訊 API（官轉）

檢索與安全

介面概述

如何獲取 Authorization

介面資訊

請求說明

請求 Headers

請求引數

響應說明

成功響應示例

核心響應欄位說明

額度換算說明

換算規則

錯誤響應

HTTP 401 - 認證失敗

HTTP 403 - 權限不足

程式碼示例

cURL 示例

Python 示例（基礎版）

Python 示例（完整最佳化版）

錯誤處理

環境變數支援

格式化輸出

自動換算

常見問題

注意事項

異常處理建議

響應格式說明

​介面概述

​如何獲取 Authorization

​介面資訊

​請求說明

​請求 Headers

​請求引數

​響應說明

​成功響應示例

​核心響應欄位說明

​額度換算說明

換算規則

​錯誤響應

​HTTP 401 - 認證失敗

​HTTP 403 - 權限不足

​程式碼示例

​cURL 示例

​Python 示例（基礎版）

​Python 示例（完整最佳化版）

錯誤處理

環境變數支援

格式化輸出

自動換算

​常見問題

​注意事項

異常處理建議

響應格式說明

介面概述

如何獲取 Authorization

介面資訊

請求說明

請求 Headers

請求引數

響應說明

成功響應示例

核心響應欄位說明

額度換算說明

錯誤響應

HTTP 401 - 認證失敗

HTTP 403 - 權限不足

程式碼示例

cURL 示例

Python 示例（基礎版）

Python 示例（完整最佳化版）

常見問題

注意事項