首页 / 文档 / 客户端配置

用量与计费 API

最后更新： 2026-07-26

LINDE AI 提供两个通过 API Key 鉴权 的开放接口，便于你用脚本、监控面板或第三方工具（如 CC-Switch）程序化查询当前 Key 的用量、额度和计费倍率。无需登录控制台，即可拿到与「使用记录」页面一致的数据。

💡 与控制台查询的区别

开放接口仅返回 当前鉴权 API Key 自身的数据，不涉及账户下其他 Key 或用户级汇总。若需跨 Key、跨账户的统计或开票数据，请登录控制台查阅或联系商务。

#接口概览

方法	路径	用途
`GET`	`/v1/usage`	查询当前 Key 的用量、额度、订阅或余额状态
`GET`	`/v1/sub2api/billing`	查询当前 Key 的计费倍率（含峰时倍率）

#鉴权方式

两个接口均在 Authorization 请求头中携带 LINDE AI 的 API Key，格式为 Bearer：

Authorization: Bearer sk-linde-xxxxxxxxxxxx

⚠️ 请妥善保管 Key

API Key 等同于凭证。不要写入前端代码、公开仓库或日志。示例中的 Key 均为虚构数据。

#请求地址

区域	Base URL
对外域名（EdgeOne CDN）	`https://ai.lindecdn.com`
回源直连（Cloudflare）	`https://ais.lindecdn.com`

完整请求示例：GET https://ai.lindecdn.com/v1/usage。

#1. 查询用量与额度

GET /v1/usage

返回 当前鉴权 API Key 的用量摘要、剩余额度、订阅状态或钱包余额。响应结构按 Key 类型自动分三种 mode：

quota_limited：有总额度或速率限制的 Key（如按次套餐、Token 套餐）
unrestricted + 订阅信息：不限量订阅套餐
unrestricted + 余额：随用随付钱包余额

#查询参数（均可选）

参数	类型	说明
`days`	int	每日用量返回天数，范围 1–90，默认 30
`start_date`	YYYY-MM-DD	模型统计的起始日期（默认近 30 天）
`end_date`	YYYY-MM-DD	模型统计的截止日期（默认今天）
`timezone`	string	时区标识，影响按日聚合的边界，如 `Asia/Shanghai`

#请求示例

curl -s "https://ai.lindecdn.com/v1/usage?days=7" \
  -H "Authorization: Bearer $LINDE_API_KEY" \
  -H "User-Agent: my-dashboard/1.0"

#响应字段说明

字段	类型	说明
`mode`	string	`quota_limited` 或 `unrestricted`
`isValid`	bool	Key 是否处于可用状态（激活 / 额度用尽 / 已过期均可能为 true，仅失效 Key 为 false）
`status`	string	Key 当前状态
`quota`	object	总额度信息，仅 `quota_limited` 模式返回
`quota.limit` / `quota.used` / `quota.remaining`	number	总额度 / 已用 / 剩余（USD）
`rate_limits`	array	速率限制窗口（5h / 1d / 7d），仅配置时返回
`rate_limits[].window`	string	窗口粒度，如 `5h`、`1d`、`7d`
`rate_limits[].limit` / `used` / `remaining`	number	窗口额度 / 已用 / 剩余（USD）
`rate_limits[].reset_at`	string	窗口重置时间（ISO 8601），仅在窗口未过期时返回
`subscription`	object	订阅信息，仅订阅型 Key 返回
`subscription.daily_limit_usd` / `weekly_limit_usd` / `monthly_limit_usd`	number	周期限额
`subscription.daily_usage_usd` / `weekly_usage_usd` / `monthly_usage_usd`	number	周期已用
`subscription.weekly_window_start`	string	周期窗口起始时间（ISO 8601）
`subscription.expires_at`	string	订阅到期时间
`remaining`	number	剩余额度：订阅取各周期最小值；余额制为钱包余额；无限制为 -1
`balance`	number	钱包余额，仅余额模式返回
`unit`	string	金额单位，固定 `USD`
`planName`	string	套餐名称（订阅型为分组名，余额型为「钱包余额」）
`expires_at`	string	Key 过期时间（ISO 8601），仅配置时返回
`days_until_expiry`	int	距过期天数
`usage`	object	今日 / 累计用量摘要，见下表
`daily_usage`	array	按日用量明细（最近 N 天），每项含 `date`、`requests`、`input_tokens`、`output_tokens`、`cache_read_tokens`、`cache_write_tokens`、`total_tokens`、`cost`、`actual_cost`
`model_stats`	array	按模型聚合的用量统计（受 `start_date`/`end_date` 影响），每项含 `model`、`requests`、各 Token 分项、`cost`、`actual_cost`、`account_cost`（上游账户成本）

#`usage` 对象字段

字段	说明
`usage.today` / `usage.total`	今日 / 累计摘要
`.requests`	请求次数
`.input_tokens` / `.output_tokens`	输入 / 输出 Token
`.cache_creation_tokens` / `.cache_read_tokens`	缓存创建 / 缓存读取 Token
`.total_tokens`	Token 合计
`.cost`	官方标准价成本
`.actual_cost`	实际扣费金额
`usage.average_duration_ms`	平均请求耗时（毫秒）
`usage.rpm` / `usage.tpm`	每分钟请求数 / 每分钟 Token 数

#响应示例

#按次套餐（quota_limited）

{
  "mode": "quota_limited",
  "isValid": true,
  "status": "active",
  "quota": {
    "limit": 9.99,
    "used": 3.42,
    "remaining": 6.57,
    "unit": "USD"
  },
  "remaining": 6.57,
  "unit": "USD",
  "rate_limits": [
    {
      "window": "5h",
      "limit": 3.00,
      "used": 0.85,
      "remaining": 2.15,
      "window_start": "2026-07-26T08:00:00Z",
      "reset_at": "2026-07-26T13:00:00Z"
    }
  ],
  "expires_at": "2026-08-02T00:00:00Z",
  "days_until_expiry": 7,
  "usage": {
    "today": {
      "requests": 18,
      "input_tokens": 12450,
      "output_tokens": 8320,
      "cache_creation_tokens": 2100,
      "cache_read_tokens": 5600,
      "total_tokens": 28470,
      "cost": 0.42,
      "actual_cost": 0.04
    },
    "total": {
      "requests": 156,
      "input_tokens": 98700,
      "output_tokens": 65400,
      "cache_creation_tokens": 12300,
      "cache_read_tokens": 42100,
      "total_tokens": 218500,
      "cost": 3.42,
      "actual_cost": 0.34
    },
    "average_duration_ms": 2340,
    "rpm": 2,
    "tpm": 1450
  },
  "daily_usage": [
    { "date": "2026-07-20", "requests": 22, "actual_cost": 0.05 },
    { "date": "2026-07-21", "requests": 18, "actual_cost": 0.04 }
  ],
  "model_stats": [
    {
      "model": "claude-sonnet-5",
      "requests": 98,
      "input_tokens": 62100,
      "output_tokens": 41200,
      "cache_read_tokens": 28400,
      "total_tokens": 131700,
      "actual_cost": 0.22
    }
  ]
}

#订阅套餐（unrestricted + 订阅）

{
  "mode": "unrestricted",
  "isValid": true,
  "planName": "GLM 编码套餐 - Max",
  "remaining": 17.31,
  "unit": "USD",
  "subscription": {
    "daily_limit_usd": 0,
    "daily_usage_usd": 3.85,
    "weekly_limit_usd": 63,
    "weekly_usage_usd": 45.69,
    "monthly_limit_usd": 0,
    "monthly_usage_usd": 45.69,
    "weekly_window_start": "2026-07-24T00:00:00+08:00",
    "expires_at": "2027-04-29T22:36:51+08:00"
  },
  "usage": {
    "today": {
      "requests": 356,
      "input_tokens": 2139601,
      "output_tokens": 186628,
      "cache_creation_tokens": 0,
      "cache_read_tokens": 28001216,
      "total_tokens": 30327445,
      "cost": 3.85,
      "actual_cost": 3.85
    },
    "total": {
      "requests": 30003,
      "input_tokens": 422790817,
      "output_tokens": 10867710,
      "cache_creation_tokens": 0,
      "cache_read_tokens": 2898242539,
      "total_tokens": 3331901066,
      "cost": 495.55,
      "actual_cost": 495.55
    },
    "average_duration_ms": 15652,
    "rpm": 1,
    "tpm": 155834
  },
  "daily_usage": [
    {
      "date": "2026-07-25",
      "requests": 1694,
      "input_tokens": 5653807,
      "output_tokens": 1072426,
      "cache_read_tokens": 194611290,
      "cache_write_tokens": 0,
      "total_tokens": 201337523,
      "cost": 33.32,
      "actual_cost": 33.32
    }
  ],
  "model_stats": [
    {
      "model": "GLM-5.2",
      "requests": 15998,
      "input_tokens": 342379643,
      "output_tokens": 6781768,
      "cache_creation_tokens": 0,
      "cache_read_tokens": 2071705088,
      "total_tokens": 2420866499,
      "cost": 146.18,
      "actual_cost": 146.18,
      "account_cost": 871.77
    }
  ]
}

#余额制（unrestricted + 钱包）

{
  "mode": "unrestricted",
  "isValid": true,
  "planName": "钱包余额",
  "remaining": 87.3421,
  "unit": "USD",
  "balance": 87.3421,
  "usage": {
    "today": { "requests": 42, "actual_cost": 1.15 },
    "total": { "requests": 1280, "actual_cost": 34.20 }
  }
}

#2. 查询计费倍率

GET /v1/sub2api/billing

返回当前 Key 的 计费倍率信息，包括分组倍率、用户专属倍率，以及峰时倍率是否生效。适合需要精确还原成本核算或做实时账单预测的场景。

ℹ️ 与 /v1/usage 的区别

/v1/usage 返回的是 已发生的用量和剩余额度；/v1/sub2api/billing 返回的是 当前 Key 的计费倍率配置。两者配合可还原「官方标准价 → 实付金额」的完整链路。

#请求示例

curl -s "https://ai.lindecdn.com/v1/sub2api/billing" \
  -H "Authorization: Bearer $LINDE_API_KEY"

#响应字段说明

字段	类型	说明
`object`	string	固定 `sub2api.key_billing`
`schema_version`	int	响应结构版本，当前为 1
`billing_scope`	string	计费范围，固定 `token`
`group_rate_multiplier`	float	分组基础倍率
`user_rate_multiplier`	float	用户专属倍率（与分组倍率不同时才返回）
`resolved_rate_multiplier`	float	最终生效的基础倍率（分组 × 用户）
`peak_rate_enabled`	bool	是否启用峰时倍率
`peak_start` / `peak_end`	string	峰时窗口起止（HH:MM:SS），仅启用时返回
`peak_rate_multiplier`	float	峰时倍率值，仅启用时返回
`applied_peak_multiplier`	float	当前时刻是否处于峰时，生效则为峰时倍率，否则为 1
`effective_rate_multiplier`	float	当前实际生效的综合倍率（`resolved_rate_multiplier × applied_peak_multiplier`）
`timezone`	string	峰时窗口所用时区，仅启用时返回
`observed_at`	string	观测时间（ISO 8601 UTC）

#响应示例

{
  "object": "sub2api.key_billing",
  "schema_version": 1,
  "billing_scope": "token",
  "group_rate_multiplier": 0.35,
  "resolved_rate_multiplier": 0.35,
  "effective_rate_multiplier": 0.35,
  "peak_rate_enabled": false,
  "observed_at": "2026-07-26T10:30:00Z"
}

启用峰时倍率时，响应会额外包含 peak_start、peak_end、peak_rate_multiplier、applied_peak_multiplier、timezone 字段。

#错误处理

所有接口在鉴权失败、参数错误或服务异常时返回统一结构：

{ "code": "INVALID_API_KEY", "message": "Invalid API key" }

#常见错误码

HTTP 状态	`code`	含义	排查建议
401	`INVALID_API_KEY`	API Key 无效或已失效	检查 Key 是否拼写正确、是否已被禁用或过期
403	`permission_error`	Key 未分配到计费分组（仅 `/billing`）	在控制台为该 Key 绑定计费分组
400	`invalid_request_error`	参数格式错误	检查 `days` 是否在 1–90，日期是否为 `YYYY-MM-DD`
429	`rate_limit_error`	触发速率限制	稀疏查询，避免高频轮询
5xx	`api_error`	服务端异常	稍后重试，持续报错请提交工单

#使用建议

#自动化监控面板

将 /v1/usage 接入 Grafana、自建 Dashboard 或 CC-Switch 卡片，实时展示剩余额度与到期倒计时。CC-Switch 的配置脚本可参考 CC-Switch 文档。

#成本核算脚本

组合两个接口还原官方标准价成本：

# 1. 取当前 Key 的综合倍率
RATE=$(curl -s "https://ai.lindecdn.com/v1/sub2api/billing" \
  -H "Authorization: Bearer $LINDE_API_KEY" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['effective_rate_multiplier'])")

# 2. 取最近 7 天的实际扣费
COST=$(curl -s "https://ai.lindecdn.com/v1/usage?days=7" \
  -H "Authorization: Bearer $LINDE_API_KEY" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['usage']['total']['actual_cost'])")

echo "实际扣费: \$$COST（倍率 ${RATE}）"

#重试与超时

遇到 429 或 5xx 时使用指数退避重试（如 1s → 2s → 4s，最多 3 次）。建议客户端设置 10 秒超时，避免长时间阻塞。

#避免高频轮询

用量数据非实时刷新（后台聚合，通常有秒级到分钟级延迟），建议查询间隔不低于 60 秒，既能及时反映用量，又不会触发速率限制。

CC-Switch

错误代码

用量与计费 API

#接口概览

#鉴权方式

#请求地址

#1. 查询用量与额度

#查询参数（均可选）

#请求示例

#响应字段说明

#usage 对象字段

#响应示例

#按次套餐（quota_limited）

#订阅套餐（unrestricted + 订阅）

#余额制（unrestricted + 钱包）

#2. 查询计费倍率

#请求示例

#响应字段说明

#响应示例

#错误处理

#常见错误码

#使用建议

#自动化监控面板

#成本核算脚本

#重试与超时

#避免高频轮询

#`usage` 对象字段