用量与余额查询

用控制台创建的 API Key 即可只读查询当前账户的通用余额或 Coding Plan 剩余额度。查询不扣费、不预留套餐额度，也不会写入用量记录。

控制台登录用户仍应使用控制台的余额与用量页面；本页的端点主要面向 CC Switch、状态栏脚本和其他需要展示「还能用多少」的外部工具。

需要直接复制四入口通用脚本时，使用 CC Switch 配置教程。该教程会自动区分人民币余额和 Coding Plan 双窗口百分比。

CC Switch 默认通用模板

CC Switch 的通用模板会用当前供应商的 Base URL 和 API Key 请求 /user/balance，并读取顶层 is_active 与 balance。Token Factory 的四个对外 Base URL 都支持这一默认路径：

权益	协议	供应商 Base URL	模板实际请求	`balance` 口径
通用余额	OpenAI 兼容	`https://tokenfactory.cn/api/v1`	`/api/v1/user/balance`	人民币元
通用余额	Anthropic Messages	`https://tokenfactory.cn/api`	`/api/user/balance`	人民币元
Coding Plan	OpenAI 兼容	`https://tokenfactory.cn/api/v1/coding`	`/api/v1/coding/user/balance`	剩余调用次数
Coding Plan	Anthropic Messages	`https://tokenfactory.cn/api/anthropic`	`/api/anthropic/user/balance`	剩余调用次数

在 CC Switch 的供应商卡片中打开「用量查询」，选择「通用模板」即可。如果供应商已配置 Token Factory Base URL 和 API Key，「API Key」与「请求地址」两个可选字段保持留空，不需要复制或维护自定义脚本。

通用余额响应示例：

json

{"is_active":true,"balance":12.345678,"unit":"CNY"}

Coding Plan 响应除了通用模板使用的 is_active / balance / unit 外，还保留下文的完整窗口字段。

CC Switch 当前版本的「通用模板」在提取器中把展示单位固定写成 USD，不会读取响应中的 unit。因此默认模板能直接查到正确数值，但 CC Switch 卡片上的单位文字可能显示为 USD；资金对账和套餐窗口判断仍以 Token Factory 控制台及本页接口口径为准。

Coding Plan 详细用量接口

GET https://tokenfactory.cn/api/v1/coding/user/balance
Authorization: Bearer <你的 API Key>

鉴权方式与 /v1/chat/completions 完全一致：用控制台创建的 API Key，放 Authorization: Bearer 头。
只读，不扣费、不落审计拒绝记录、不预留额度。

失败统一返回 OpenAI 风格错误体，例如 401：

json

{"error":{"message":"无效的 API Key","type":"authentication_error","code":"invalid_api_key"}}

响应字段

成功（HTTP 200）返回如下结构。字段分四组：窗口限制、周期额度、并发，以及一组扁平兼容字段让不同工具各取所需。

字段	类型	含义
`active`	bool	当前账户是否有可用 Coding Plan
`is_active`	bool	CC Switch 通用模板字段：当前套餐是否仍有可用额度
`balance`	long	CC Switch 通用模板字段：与 `remaining` 相同的剩余调用次数
`planName`	string	套餐计划名
`fiveHour`	object	5 小时滚动窗口（按调用次数）
`fiveHour.limit` / `used` / `remaining`	long	上限 / 已用 / 剩余（次）
`fiveHour.usedPercent`	int	已用百分比 0–100
`fiveHour.resetAt`	string	窗口恢复时间（ISO-8601）
`weekly`	object	每周滚动窗口（按调用次数，按开通锚点对齐）
`weekly.limit` / `used` / `remaining`	long	上限 / 已用 / 剩余（次）
`weekly.usedPercent`	int	已用百分比 0–100
`weekly.windowStart` / `windowEnd`	string	当前周窗口起止（ISO-8601）
`concurrency.limit` / `inFlight`	int	并发上限 / 当前占用
`pkg`	object	套餐周期 token 额度（兼容字段）
`pkg.quotaTokens` / `usedTokens` / `remainingTokens`	long	总额度 / 已用 / 剩余（token）
`pkg.usagePercent`	int	token 已用百分比 0–100
`pkg.periodStart` / `periodEnd`	string	套餐周期起止
`pkg.supportedModels`	string[]	套餐支持的模型 ID
`remaining`	long	扁平字段：5 小时与每周窗口剩余次数的较小值
`unit`	string	固定 `calls`
`isValid`	bool	扁平字段：套餐有效且仍有剩余
`quota`	long	扁平字段：5 小时窗口上限（OneAPI 风格）
`usedQuota`	long	扁平字段：5 小时窗口已用（OneAPI 风格）
`capturedAt`	string	快照时间（ISO-8601）
`message`	string	无套餐时的提示文案

完整响应示例

json

{
  "active": true,
  "is_active": true,
  "balance": 380,
  "planName": "GLM Coding Pro",
  "fiveHour": {
    "limit": 500,
    "used": 120,
    "remaining": 380,
    "usedPercent": 24,
    "resetAt": "2026-07-17T10:00:00Z"
  },
  "weekly": {
    "limit": 3000,
    "used": 800,
    "remaining": 2200,
    "usedPercent": 26,
    "windowStart": "2026-07-14T07:00:00Z",
    "windowEnd": "2026-07-21T07:00:00Z"
  },
  "concurrency": { "limit": 5, "inFlight": 1 },
  "pkg": {
    "quotaTokens": 20000000,
    "usedTokens": 5400000,
    "remainingTokens": 14600000,
    "usagePercent": 27,
    "periodStart": "2026-07-01T00:00:00Z",
    "periodEnd": "2026-08-01T00:00:00Z",
    "supportedModels": ["glm-4.6", "glm-4.5-air"]
  },
  "remaining": 380,
  "unit": "calls",
  "isValid": true,
  "quota": 500,
  "usedQuota": 120,
  "capturedAt": "2026-07-17T07:00:00Z",
  "message": null
}

无套餐时的响应

json

{
  "active": false,
  "is_active": false,
  "balance": 0,
  "planName": null,
  "fiveHour": null,
  "weekly": null,
  "concurrency": null,
  "pkg": null,
  "remaining": 0,
  "unit": "calls",
  "isValid": false,
  "quota": 0,
  "usedQuota": 0,
  "capturedAt": "2026-07-17T07:00:00Z",
  "message": "当前账户没有可用编程套餐"
}

三类工具的对接方式

不同工具认不同字段名。下面给出三种主流对接写法；选与你所用工具匹配的一种即可。

1. NewAPI / OneAPI 风格（quota / usedQuota）

NewAPI 生态的额度查询约定是「总额度 quota、已用 used_quota、剩余 = quota − used_quota」。本接口的扁平字段 quota / usedQuota / remaining 已对齐这一口径（取 5 小时窗口，因为它是 Coding Plan 的主用限制）。

curl 示例：

bash

curl -s https://tokenfactory.cn/api/v1/coding/user/balance \
  -H "Authorization: Bearer sk-tf-xxxxxx"

取值对照：

NewAPI 语义	本接口字段
`quota`（总额度）	`quota`
`used_quota`（已用）	`usedQuota`
`balance`（剩余 = quota − used_quota）	`remaining`
Key 是否可用	`isValid`

自定义外挂脚本（Node.js，可直接套用你已有的 extractor 形状）：

// 请求
const res = await fetch("https://tokenfactory.cn/api/v1/coding/user/balance", {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();

// 适配 extractor:返回 { remaining, unit, isValid }
module.exports = {
  isValid: body.isValid,
  remaining: body.remaining,
  unit: "calls",
};

说明：Coding Plan 的主用限制是「调用次数」而非人民币余额，因此 unit 为 calls，不要把它当作 USD / CNY 金额展示。

2. Claude Code 插件 / glm-plan-usage 风格（百分比 + 重置时间）

智谱官方 glm-plan-usage 插件读取的是 limits[].percentage（5 小时 token、每周 MCP）。本接口的 fiveHour.usedPercent / weekly.usedPercent + fiveHour.resetAt / weekly.windowEnd 直接对齐这一形状。

取值对照：

glm-plan-usage 语义	本接口字段
TOKENS_LIMIT（5 小时已用百分比）	`fiveHour.usedPercent`
5 小时窗口恢复时间	`fiveHour.resetAt`
每周已用百分比	`weekly.usedPercent`
每周窗口结束时间	`weekly.windowEnd`

自定义查询脚本（Python，输出与 glm-plan-usage 相似的双窗口百分比）：

python

import requests, os

r = requests.get(
    "https://tokenfactory.cn/api/v1/coding/user/balance",
    headers={"Authorization": f"Bearer {os.environ['TF_API_KEY']}"},
).json()

print(f"5 小时窗口:  已用 {r['fiveHour']['usedPercent']}%, 恢复于 {r['fiveHour']['resetAt']}")
print(f"每周窗口:    已用 {r['weekly']['usedPercent']}%, 结束于 {r['weekly']['windowEnd']}")
print(f"并发占用:    {r['concurrency']['inFlight']}/{r['concurrency']['limit']}")

3. 通用 HTTP / curl（取全部字段）

任何能发 HTTP 请求的工具（状态栏脚本、定时监控、Grafana 数据源等）都可直接调用。下面给出完整的 jq 解析示例：

bash

# 一行看核心
curl -s https://tokenfactory.cn/api/v1/coding/user/balance \
  -H "Authorization: Bearer sk-tf-xxxxxx" \
| jq '{fiveHour: .fiveHour.remaining, weekly: .weekly.remaining, reset: .fiveHour.resetAt}'

输出：

json

{ "fiveHour": 380, "weekly": 2200, "reset": "2026-07-17T10:00:00Z" }

低额度告警示例（5 小时窗口剩余 < 10% 时报警）：

bash

REMAINING_PERCENT=$(curl -s https://tokenfactory.cn/api/v1/coding/user/balance \
  -H "Authorization: Bearer sk-tf-xxxxxx" \
| jq '100 - .fiveHour.usedPercent')

if [ "$REMAINING_PERCENT" -lt 10 ]; then
  echo "⚠️ 5 小时窗口剩余 ${REMAINING_PERCENT}%，即将耗尽"
fi

注意事项

本接口返回的是 Coding Plan 窗口用量，不是人民币余额。如果你的账户走的是通用余额（按量计费）而非 Coding Plan，active 会是 false。
remaining 与 balance 取 5 小时、每周两个窗口剩余次数的较小值。两个窗口同时约束调用，任一窗口耗尽时都返回 0，避免状态栏显示仍可调用但网关实际拒绝。
5 小时窗口按调用恢复（resetAt ≈ 当前时间 + 5 小时）；每周窗口按套餐开通锚点每 7 天滚动。
请用可撤销的 API Key，不要把 Key 写入公开仓库或聊天记录。Key 失效后本接口返回 401。

复验与失效条件

本教程为 待复验。API 字段、鉴权方式、窗口口径或套餐模型范围发生变化后，结论退回复验。

用量与余额查询 ​

CC Switch 默认通用模板 ​

Coding Plan 详细用量接口 ​

响应字段 ​

完整响应示例 ​

无套餐时的响应 ​

三类工具的对接方式 ​

1. NewAPI / OneAPI 风格（quota / usedQuota） ​

2. Claude Code 插件 / glm-plan-usage 风格（百分比 + 重置时间） ​

3. 通用 HTTP / curl（取全部字段） ​

注意事项 ​

复验与失效条件 ​

用量与余额查询

CC Switch 默认通用模板

Coding Plan 详细用量接口

响应字段

完整响应示例

无套餐时的响应

三类工具的对接方式

1. NewAPI / OneAPI 风格（quota / usedQuota）

2. Claude Code 插件 / glm-plan-usage 风格（百分比 + 重置时间）

3. 通用 HTTP / curl（取全部字段）

注意事项

复验与失效条件