文档
管理 API
管理 Key 让你自己的系统通过 API 创建、分组、限额和撤销账户的 API Key,并读取它们的花费。它不能调用模型。
适用场景
有些集成会给每个客户、团队或用户各发一把 API Key,把每个客户的 Key 放进一个分组,限制分组能花多少,再按 Key 或按分组读回花费。Key 不多时,在 API 密钥页面操作就够了;Key 多了,可以用管理 Key 让脚本或你自己的管理工具通过 API 完成同样的事。
管理 Key 与 API Key 是两种不同的凭证。API Key 能用的地方它不能用:它不能调用 /v1/chat/completions、/v1/messages 或任何其他模型路由,只能用于 /v1/management/,而 API Key 在那里不起作用。
创建管理 Key
- 打开 API 密钥页面,滑到页面底部。在“管理 Key”下选择“新建管理 Key”。这个区块默认折叠,打开后才会显示。
- 给 Key 起个名字,例如 billing sync,这样页面就能说明每次变更是哪个程序做的。
- 填入允许调用它的地址,每行一个:可以是单个地址,如 203.0.113.7,也可以是地址段,如 203.0.113.0/24。没有白名单时,任何拿到这把 Key 的人都能使用它;白名单留空时,对话框会提示你。
- Key 显示出来时请立即复制。它只显示一次:Kunavo 只保存它的哈希。
一个账户同时最多有两把生效中的管理 Key。撤销其中一把,才能再建新的。
调用方式
把 Key 作为 Bearer 令牌发送到 https://api.kunavo.com/v1/management。管理 Key 不接受来自浏览器的调用:它的响应不带 CORS 头,所以其他网站上的页面无法调用。Key 只应放在你的服务器上,不要放进前端代码。
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"响应是 JSON。错误的格式与 API 的其他部分一致:一个 error 对象,包含 message、type、code,以及(在适用时)出错的 param。你会遇到这些状态码:
| 状态码 | 含义 |
|---|---|
401 | Key 缺失、写错或已撤销,或其账户已被停用或正在审核。 |
403 | 这把 Key 设了 IP 白名单,而请求来自不在名单上的地址。 |
404 | 分组或 Key 不存在、已删除,或属于其他账户。三种情况的响应完全一样,所以拿其他账户的 id 来试探不会泄露任何信息。 |
409 | 这次变更与账户当前状态冲突:分组名已被占用、Key 已撤销,或账户已达到 500 把生效中 Key 的上限。 |
429 | 这把 Key 在最近一分钟内已发出 60 次请求。Retry-After 响应头会告诉你要等多少秒。 |
分组
GET /v1/management/groups 列出账户的分组,附每个分组的月度上限和其中生效中的 Key 数。POST 新建分组,可带可选的 monthly_limit_usd;名称已被占用时返回 409。PATCH /v1/management/groups/{id} 修改名称或上限:发送 null 表示不限,发送 0 则暂停组内所有 Key 而不撤销任何一把。DELETE 删除分组,它的调用在用量页面上仍保留它的名称。它的 Key 保持生效并变为未分组;如果加上 ?revoke_keys=true,这些 Key 也会一并撤销。
curl https://api.kunavo.com/v1/management/groups \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001", "monthly_limit_usd": 50}'Key
GET /v1/management/keys 按新建时间从新到旧列出 Key。每页 50 把,用 limit 可提高到 100。status 默认为 active,也可以是 revoked 或 all,group_id 则把列表限定到某一个分组。当 has_more 为 true 时,把 next_after 设为 after 即可读取下一页。列表中永远不会出现 Key 的明文。
POST /v1/management/keys 创建一把 Key,需要名称,可选 group_id、monthly_limit_usd 和 ip_allowlist。明文只在响应的 key 字段里出现一次。重复发送 POST 会创建第二把 Key,所以重试之前,请先列出 Key,查找这个名称。
curl https://api.kunavo.com/v1/management/keys \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'PATCH /v1/management/keys/{id} 修改 Key 的名称、分组、上限或白名单;把 group_id 设为 null 可把它移出分组。DELETE 撤销它。撤销已撤销的 Key 不算错误。已撤销的 Key 不能再修改。
curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"用量
GET /v1/management/usage 报告整个账户在最长 90 个 UTC 日内的用量,GET /v1/usage 则报告单把 Key 的用量。group_by 接受 group、api_key、model 和 day 的任意组合,默认为 api_key。数字的含义与用量页面一致:调用算在发生时 Key 所在的分组,失败的调用不收费,某一时段的合计与同一时段 CSV 导出的合计精确到分一致。group_id 和 api_key_id 把报告限定到某一个分组或某一把 Key。
curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
-H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"end_date 按今天处理,响应会回显实际采用的结束日期。妥善保管
- 设置白名单。只能从你服务器的地址使用的 Key,被人偷走后价值不大。
- 把 Key 放在运行你的工具的服务器上的密钥存储里。不要放进浏览器、移动应用或代码仓库。
- 如果泄露,请在 API 密钥页面底部撤销它,或对它调用
DELETE。撤销对话框还可以一并撤销这把 Key 创建的 Key。 - 这把 Key 通过 API 做出的每一次变更,都列在 API 密钥页面的“管理 Key”下,附时间、来源地址和执行变更的 Key,保留最近 50 条。在该页面手动做的变更不在其中。
- 账户被停用或进入审核时,以及 Key 被撤销时,Key 会自动失效。
一把管理 Key 每分钟最多发出 60 次请求。每次变更发一次请求,读取列表时请分页读取,不要一把 Key 一把 Key 地查。