查询 API Key 余额 | ToAPIs Documentation

GET

/api/v1/api-keys/{api_key_id}/balance

国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.

使用说明

读取指定 Key 的剩余额度快照, 用于查看它还能消耗多少. 停用, 过期, 耗尽和已软删除的 Key 都可以读取; 属于他人或不存在的 Key 返回 404.

返回的是数据库中已保存的余额快照, 不是实时计算的数值: 无限额度 Key 的剩余金额为 null, 已用金额正常返回. 日/月限额的实时已用计数不在本接口读取范围; 调用扣费按批次写入数据库, 批次尚未落库时, 读到的数值会略滞后于实际用量.

鉴权

Authorizationstring请求头必填

系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 不接受模型 Key, 无需 X-User-Id. 共用规则见接入方式.

请求参数

api_key_idstring路径必填

自有普通模型 Key 的十进制 ID 字符串, 不是 sk- 密钥.

此接口不接受请求体或查询参数.

请求示例

curl --request GET \
  --url 'https://api.toapis.com/api/v1/api-keys/43/balance' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

import requests

response = requests.get(
    "https://api.toapis.com/api/v1/api-keys/43/balance",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys/43/balance", {
  method: "GET",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

响应字段

示例使用虚构数据. Key 元数据字段见获取 API Key 详情, 通用响应和错误处理见接入方式.

data.api_key_idstring

Key ID.

data.statusstring

Key 当前状态, 包含 deleted.

data.unlimitedboolean

是否无限额度.

data.remaining_creditsstring | null

剩余额度, 单位 credits; 无限时为 null.

data.remaining_usdstring | null

剩余额度折算 USD; 无限时为 null.

data.used_creditsstring

累计已用额度, 单位 credits.

data.used_usdstring

累计已用额度折算 USD.

data.daily_limit_creditsstring | null

每日限额, 无限制时为 null.

data.monthly_limit_creditsstring | null

每月限额, 无限制时为 null.

data.credits_per_usdstring

每 1 USD 对应的 credits 数量.

响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": "43",
    "status": "enabled",
    "unlimited": false,
    "remaining_credits": "500",
    "remaining_usd": "5",
    "used_credits": "100",
    "used_usd": "1",
    "daily_limit_credits": null,
    "monthly_limit_credits": null,
    "credits_per_usd": "100"
  }
}