查询用量与额度

GET/user/balance

鉴权

Bearer API Key

执行方式

按所调用的完整地址执行

查看调用示例

接口说明

使用 Bearer API Key 只读查询 Coding Plan 的窗口、并发与周期用量；不会发起模型调用，不预留套餐，也不产生计费。

请求

请求地址

• 方法：GET

• 鉴权：Authorization: Bearer ${TOKENFACTORY_API_KEY}

请求头

名称	必填	值或类型	说明
Authorization	是	Bearer ${TOKENFACTORY_API_KEY}	Token Factory API Key

路径参数：无

查询参数：无

请求字段：无

请求报文：无请求体

响应

成功状态：200

响应头

名称	值或类型	说明
Content-Type	application/json	响应媒体类型

响应字段

字段	类型	必填	说明	示例或约束
active	boolean	是	当前账户是否存在有效 Coding Plan。	示例：true
balance	integer (int64)	是	兼容字段：5 小时与每周窗口剩余调用次数的较小值。	示例：128；最小值：0
capturedAt	string (date-time)	是	生成本次用量快照的时间。	示例："2026-08-27T12:00:00Z"
concurrency	object	是	查询时刻的并发占用快照；无有效套餐时为 null。	示例：{"inFlight":1,"limit":5}；可为 null
concurrency.inFlight	integer (int32)	是	查询时刻正在执行的调用数。	示例：1；最小值：0
concurrency.limit	integer (int32)	是	套餐允许的最大并发调用数。	示例：3；最小值：0
fiveHour	object	是	5 小时滚动窗口用量；无有效套餐时为 null。	示例：{"limit":500,"remaining":380,"resetAt":"2026-08-28T03:00:00Z","used":120,"use...；可为 null
fiveHour.limit	integer (int64)	是	5 小时窗口调用次数上限。	示例：500；最小值：0
fiveHour.remaining	integer (int64)	是	5 小时窗口剩余调用次数。	示例：380；最小值：0
fiveHour.resetAt	string (date-time)	是	当前 5 小时滚动窗口的额度恢复时间。	示例："2026-08-27T15:00:00Z"
fiveHour.used	integer (int64)	是	5 小时窗口已用调用次数。	示例：120；最小值：0
fiveHour.usedPercent	integer (int32)	是	5 小时窗口已用百分比，范围 0 到 100。	示例：24；最小值：0；最大值：100
isValid	boolean	是	兼容字段，与 is_active 含义相同。	示例：true
is_active	boolean	是	当前套餐是否仍有可用调用次数；任一窗口耗尽时为 false。	示例：true
message	string	是	无有效套餐时的原因说明；正常有效时为 null。	示例："当前没有可用套餐"；可为 null
pkg	object	是	套餐周期 Token 额度兼容视图；无有效套餐时为 null。	示例：{"periodEnd":"2026-09-12T22:00:00Z","periodStart":"2026-08-12T22:00:00Z","quo...；可为 null
pkg.periodEnd	string (date-time)	是	当前套餐周期结束时间。	示例："2026-09-01T00:00:00Z"
pkg.periodStart	string (date-time)	是	当前套餐周期开始时间。	示例："2026-08-01T00:00:00Z"
pkg.quotaTokens	integer (int64)	是	当前套餐周期 Token 总额度。	示例：10000000；最小值：0
pkg.remainingTokens	integer (int64)	是	当前套餐周期剩余 Token 数。	示例：7500000；最小值：0
pkg.supportedModels	string[]	是	当前套餐允许调用的模型 ID 列表。	示例：["glm-5","deepseek-v3"]
pkg.usagePercent	integer (int32)	是	当前套餐周期 Token 已用百分比，范围 0 到 100。	示例：25；最小值：0；最大值：100
pkg.usedTokens	integer (int64)	是	当前套餐周期已用 Token 数。	示例：2500000；最小值：0
planName	string	是	当前套餐名称；无有效套餐时为 null。	示例："Coding Pro"；可为 null
quota	integer (int64)	是	兼容字段：5 小时窗口调用次数上限。	示例：500；最小值：0
remaining	integer (int64)	是	当前可继续调用的次数，取两个窗口剩余量的较小值。	示例：128；最小值：0
unit	string	是	窗口额度单位，固定为调用次数。	示例："calls"；可选值："calls"
usedQuota	integer (int64)	是	兼容字段：5 小时窗口已用调用次数。	示例：120；最小值：0
weekly	object	是	按套餐开通锚点对齐的每周窗口用量；无有效套餐时为 null。	示例：{"limit":3000,"remaining":2200,"used":800,"usedPercent":26,"windowEnd":"2026-...；可为 null
weekly.limit	integer (int64)	是	每周窗口调用次数上限。	示例：2000；最小值：0
weekly.remaining	integer (int64)	是	每周窗口剩余调用次数。	示例：1520；最小值：0
weekly.used	integer (int64)	是	每周窗口已用调用次数。	示例：480；最小值：0
weekly.usedPercent	integer (int32)	是	每周窗口已用百分比，范围 0 到 100。	示例：24；最小值：0；最大值：100
weekly.windowEnd	string (date-time)	是	当前每周窗口结束和额度恢复时间。	示例："2026-08-31T00:00:00Z"
weekly.windowStart	string (date-time)	是	当前每周窗口开始时间。	示例："2026-08-24T00:00:00Z"

返回报文

媒体类型：application/json

套餐有效且仍有可用额度

示例标识：active

{
  "active": true,
  "balance": 380,
  "capturedAt": "2026-08-27T22:00:00Z",
  "concurrency": {
    "inFlight": 1,
    "limit": 5
  },
  "fiveHour": {
    "limit": 500,
    "remaining": 380,
    "resetAt": "2026-08-28T03:00:00Z",
    "used": 120,
    "usedPercent": 24
  },
  "isValid": true,
  "is_active": true,
  "message": null,
  "pkg": {
    "periodEnd": "2026-09-12T22:00:00Z",
    "periodStart": "2026-08-12T22:00:00Z",
    "quotaTokens": 20000000,
    "remainingTokens": 14600000,
    "supportedModels": [
      "YOUR_MODEL_ID"
    ],
    "usagePercent": 27,
    "usedTokens": 5400000
  },
  "planName": "Coding Plan",
  "quota": 500,
  "remaining": 380,
  "unit": "calls",
  "usedQuota": 120,
  "weekly": {
    "limit": 3000,
    "remaining": 2200,
    "used": 800,
    "usedPercent": 26,
    "windowEnd": "2026-08-28T22:00:00Z",
    "windowStart": "2026-08-21T22:00:00Z"
  }
}

套餐有效但当前窗口额度已耗尽

示例标识：exhausted

{
  "active": true,
  "balance": 0,
  "capturedAt": "2026-08-27T22:05:00Z",
  "concurrency": {
    "inFlight": 1,
    "limit": 5
  },
  "fiveHour": {
    "limit": 500,
    "remaining": 0,
    "resetAt": "2026-08-28T03:00:00Z",
    "used": 500,
    "usedPercent": 100
  },
  "isValid": false,
  "is_active": false,
  "message": null,
  "pkg": {
    "periodEnd": "2026-09-12T22:00:00Z",
    "periodStart": "2026-08-12T22:00:00Z",
    "quotaTokens": 20000000,
    "remainingTokens": 14600000,
    "supportedModels": [
      "YOUR_MODEL_ID"
    ],
    "usagePercent": 27,
    "usedTokens": 5400000
  },
  "planName": "Coding Plan",
  "quota": 500,
  "remaining": 0,
  "unit": "calls",
  "usedQuota": 500,
  "weekly": {
    "limit": 3000,
    "remaining": 2200,
    "used": 800,
    "usedPercent": 26,
    "windowEnd": "2026-08-28T22:00:00Z",
    "windowStart": "2026-08-21T22:00:00Z"
  }
}

当前没有可用套餐

示例标识：inactive

{
  "active": false,
  "balance": 0,
  "capturedAt": "2026-08-27T22:10:00Z",
  "concurrency": null,
  "fiveHour": null,
  "isValid": false,
  "is_active": false,
  "message": "当前没有可用套餐",
  "pkg": null,
  "planName": null,
  "quota": 0,
  "remaining": 0,
  "unit": "calls",
  "usedQuota": 0,
  "weekly": null
}

错误

适用完整地址	状态	错误码	常见触发	重试	建议动作	结果风险
https://api.tokenfactory.cn/v1/coding/user/balance	401	invalid_api_key	Authorization 缺失、Bearer 格式错误、Key 不可用或账户未实名	否	检查 Bearer API Key、Key 状态与实名状态	无
https://api.tokenfactory.cn/v1/coding/user/balance	500	internal_error	平台内部出现未预期错误	视情况	确认未收到有效结果并记录请求时间后再决定是否重试	中到高

错误返回报文

适用完整地址

https://api.tokenfactory.cn/v1/coding/user/balance

HTTP 401；Content-Type: application/json

{
  "error": {
    "code": "invalid_api_key",
    "message": "Authorization 缺失、Bearer 格式错误、Key 不可用或账户未实名",
    "type": "authentication_error"
  }
}

限制与计费

适用完整地址	限制或计费说明
https://api.tokenfactory.cn/v1/coding/user/balance	只读查询，不预留套餐、不扣减额度、不产生计费。 返回 5 小时、每周、并发与周期 Token 快照；无可用套餐仍返回 200。 此接口只读；返回当次查询快照，不代表实时账单明细。

调用示例

cURL · https://api.tokenfactory.cn/v1/coding/user/balance

curl --request GET "https://api.tokenfactory.cn/v1/coding/user/balance" --silent --show-error --fail-with-body --max-time 60 --header "Authorization: Bearer ${TOKENFACTORY_API_KEY}"

相关说明

这是只读的本地权益快照，使用固定响应结构，不发起模型调用或供应商上游请求。错误统一使用 OpenAI 风格 JSON 信封。

• 兼容性说明

• 错误处理

• 流式与重试