变更历史
公共 API 的兼容期旧路径, 旧接口替代关系和迁移差异
2026-11-12
本次更新重新整理了公共 API 文档: 页面现在按账户, API Key, 用量, 任务, 账单和定价分组, 并补齐了 Key 生命周期 (创建, 更新, 吊销, 轮换), Key 余额和模型定价的接口文档. 原 "账户" 分组下的 5 个页面已删除, 旧文档地址会重定向到对应的新页面. 本次只调整文档结构, 线上接口行为不变.
兼容期旧路径
下列 10 个 GET 旧路径仍可使用, 行为与右侧新路径完全相同. 它们仅为兼容保留, 将在后续版本移除, 请尽快迁移; 新接入请直接使用新路径. 注意 /api/v1/account 和 /api/v1/account/balance 本身就是新路径, 不在此列.
| 旧路径 | 新路径 |
|---|---|
/api/v1/account/api-keys | /api/v1/api-keys |
/api/v1/account/api-keys/{api_key_id} | /api/v1/api-keys/{api_key_id} |
/api/v1/account/usage/records | /api/v1/usage/records |
/api/v1/account/usage/summary | /api/v1/usage/summary |
/api/v1/account/tasks | /api/v1/tasks |
/api/v1/account/tasks/{task_id} | /api/v1/tasks/{task_id} |
/api/v1/account/billing/topups | /api/v1/billing/topups |
/api/v1/account/billing/topups/{trade_no} | /api/v1/billing/topups/{trade_no} |
/api/v1/account/billing/payment-method | /api/v1/billing/payment-method |
/api/v1/account/billing/auto-topup | /api/v1/billing/auto-topup |
创建, 更新, 吊销, 轮换 Key, Key 余额, Webhook, 定价和 Stripe 发票这些接口本身就没有 /account 前缀的旧路径, 只有新路径.
旧账户接口迁移
下表是新旧接口的功能对应关系, 不是可直接替换的兼容路径: 两边的凭据, 参数和响应结构不同, 需要同步修改调用代码. 旧余额和创建接口用模型 Key 认证, 新接口改用系统访问令牌; 旧用量接口还要求 X-User-Id 头, 新接口不再需要.
| 旧接口 | 新接口 | 迁移条件 |
|---|---|---|
GET /v1/balance, /balance | GET /api/v1/api-keys/{api_key_id}/balance | 用系统访问令牌和 Key ID 读取快照, 不再用待查询 Key 自身认证. 无限剩余额度为 null, 不用 -1. |
GET /api/usage/tokens/requests | GET /api/v1/usage/records | 字段与参数迁移见下表. 缓存读取与写入量位于 usage 对象内. |
GET /api/usage/tokens/summary | GET /api/v1/usage/summary?group_by=api_key | 显式传 group_by=api_key. record_count 是日志条数, 不是完整请求数或最终净支出. |
GET /v1/user/balance, /user/balance | GET /api/v1/account/balance | 读取自身账户余额或子账号预算. 金额使用十进制字符串, 明确返回 USD 和 credits. |
GET /v1/pricing | GET /api/v1/pricing?api_key_id={api_key_id} | 传 api_key_id 可选 Key 视角. after/next_after 改为 cursor/next_cursor, 响应使用 code/message/data, 不是同一协议. |
POST /v1/tokens | POST /api/v1/api-keys | 新请求字段及类型见创建文档. 不支持 group, cross_group_retry 或 Webhook 配置, 因此不是旧接口全部能力的替代. |
旧 allow_ips 使用换行分隔的字符串, 新接口改为字符串数组, 例如 ["192.0.2.10","2001:db8::1"]. 创建和更新接口都支持该字段: 传 [] 清除限制, 传 null 或非法地址返回 400. 只支持单个 IP 地址, 不支持 CIDR 网段.
用量字段和分页迁移
时间参数由旧 start_timestamp/end_timestamp (Unix 秒) 改为带时区的 from/to, 翻页时保持同一时间范围. token_id 改为 api_key_id 字符串, page_size 改为 limit. 旧游标不能用于新接口.
缓存字段方面: 旧 cache_tokens 对应 usage.cache_read_tokens, cache_creation_tokens 对应 usage.cache_write_tokens. 新接口额外提供 5 分钟和 1 小时写入拆分, 拆分值已计入 cache_write_tokens, 不要重复相加.
字段缺失或无效时返回 null, 明确记录的零返回 0.
参数错误的 HTTP 状态由 422 改为 400, 错误响应使用数字 code. 旧 quota 字段是内部额度单位, 新 recorded_credits 已换算为 credits, 迁移时要调整金额口径而不能只改字段名.
| 旧字段 | 新字段 | 说明 |
|---|---|---|
log_id | id | 仅改名. |
token_id | api_key_id | 数字 ID, 以字符串传递. |
token_name | key_name | 仅改名. |
model_name | model | 仅改名. |
start_timestamp/end_timestamp | from/to | Unix 秒 → 带时区的 RFC 3339; 翻页时保持同一时间范围. |
page_size | limit | 每页条数. |
cost_usd | recorded_cost_usd | 该日志行的入账成本 USD, 十进制字符串. |
quota | recorded_credits | 内部额度单位 → 已换算的 credits, 不能直接沿用旧数值. |
prompt_tokens | usage.input_tokens | 移入 usage 对象. |
completion_tokens | usage.output_tokens | 移入 usage 对象. |
reported_total_tokens | usage.reported_total_tokens | 上游汇报的总 token 数; 移入 usage 对象. |
cache_tokens | usage.cache_read_tokens | 缓存读取量; 移入 usage 对象. |
cache_creation_tokens | usage.cache_write_tokens | 缓存写入总量, 已含 5 分钟和 1 小时拆分, 不要重复相加. |
request_count | record_count | 日志条数, 不是完整请求数. |
data[] | data.items[] | 记录数组移入 data.items. |
meta.has_more | data.has_more | 分页信息移入 data. |
meta.next_cursor | data.next_cursor | 翻页游标; 旧游标对新接口无效. |
创建 Key 的字段变化
| 旧字段 | 新字段 | 说明 |
|---|---|---|
expired_time | expires_at | Unix 秒 (-1 表示永不过期) 改为带时区的 RFC 3339; null 或省略表示永不过期. |
remain_quota/remain_credits | remaining_credits | 十进制字符串, 保留精度. |
daily_credits/monthly_credits | daily_limit_credits/monthly_limit_credits | null 或 "0" 表示不限额. |
unlimited_quota | unlimited | 布尔值, 不接受 null; true 时 remaining_credits 只能省略或为 null. |
model_limits_enabled | — | 已移除; model_limits 数组非空即启用限制. |
model_limits | model_limits | 逗号分隔字符串 → 字符串数组; 拼接后最多 1024 UTF-8 字节. |
allow_ips | allow_ips | 换行分隔字符串 → 字符串数组; 仅单个 IP, 不支持 CIDR; [] 清除, null/非法地址返回 400. |
行为变化: 创建成功的 HTTP 状态由 200 改为 201, 完整密钥从 data.key 返回, 已包含 sk- 前缀.
迁移后仍需区分的能力
账户任务接口只提供任务状态和账务元数据, 生成结果仍需使用原有的结果查询接口. billing 和 usage 字段的含义见实际费用与任务用量. 定价目录只反映当前费率, 不能用来重新计算历史账单.
公共 API 的 Key 管理也不支持修改额度或恢复已吊销的 Key.
Webhook 通过独立的配置接口管理: 每个普通模型 Key 对应一份配置, 与 Key 的创建和更新是分开的操作. 详见查询 Webhook 配置.