文档
Key 分组
给每个客户发各自的 API Key,把它们放进一个分组,随时读出任一时段里每个客户、每把 Key 花了多少,并限制每个客户一个月最多能花多少。一个账户,一个余额。
分组是账户里的一个 API Key 文件夹,比如每个客户一个:CID000001、CID000002。组里的 Key 调用 API 和其他 Key 完全一样,分组也没有自己的余额、充值或登录;分组可以设一个月度上限,按组内全部 Key 合计。一把 Key 属于一个分组,或不属于任何分组。
三步建好分组
读出一个月并导出
在用量页面顶部选“上月”(或“本月”,或用“自定义”选日期)。在“按 API Key”里,每个分组的标题行显示它的花费和调用次数。页面顶部的分组菜单可以把整页缩小到一个分组:它的数字、曲线、模型和调用记录。“导出 CSV”下载的就是页面当前显示的内容:同一个时间范围、同一个分组,可按 Key 汇总,也可按天。
按 Key 汇总时,文件每把 Key 在每个分组下一行,文件名形如 kunavo-cost-by-key_2026-10-01_2026-10-31.csv。它列出时间范围内有调用的每把 Key(含已撤销的),放在每次调用发生时所在的分组下;以及在当前所在分组里没有调用的每把可用 Key(记为 0),所以每个客户的 Key 名单是完整的。分组按控制台里的顺序排列,组内的 Key 按花费从高到低,未分组的 Key 排在最后。按天导出时,文件第一列是 date,每把 Key 在某个分组里有调用的每一天一行。
| 列 | 内容 |
|---|---|
group | 调用发生时所在的分组;不属于任何分组的调用为空。之后被删除的分组,名字后面带 (deleted)。 |
key_name | Key 的名称。 |
key_prefix | Key 的开头部分,和控制台里显示的一样。不会是完整的 Key。 |
key_status | active 或 revoked。 |
calls | 这把 Key 在时间范围内的调用次数。 |
errors | 其中失败的调用次数。失败的调用不收费。 |
input_tokens | 输入 token 数,含缓存读取和缓存写入。 |
output_ | 输出 token 数。 |
cached_ | 输入 token 中从提示缓存读取的部分。 |
cache_ | 输入 token 中写入提示缓存的部分。 |
cost_usd | 这些调用的扣费金额,单位美元,保留八位小数。 |
=、+、- 或 @ 开头的分组名或 Key 名,导出时前面加一个单引号,这样电子表格会把它当作文本显示,而不是当作公式执行。限制每个分组一个月的花费
在 API 密钥页面打开分组的菜单,选“设置月度上限”。这个上限按分组内全部 Key 在一个自然月(UTC)里的合计花费计算,也就是每把 Key 在该分组期间产生的调用。会让分组超过上限的请求会以 402 被拒绝,且不收取任何费用。留空表示不限;填 0 可以在不撤销任何 Key 的前提下暂停组里的所有 Key。
每把 Key 自己的月度上限照常生效,先达到哪个,就由哪个拒绝请求。分组标题显示本月花费对上限的进度;请求开始被拒绝后显示“已到上限”,上限为 0 时显示“已暂停”。
当一个分组,或设了自身上限的一把 Key,本月用到上限的 80% 时,Kunavo 会给你的账户邮箱发一封信;请求开始因这个上限被拒绝时再发一封。每个上限每种信每月最多一封。
数字怎么算
- 花费就是扣费金额。每次调用的花费,是它完成时从你的余额里扣掉的金额。失败的调用不收费。
- 月和日都按 UTC。本月从 1 日 00:00 UTC 开始。比如在仰光(UTC+6:30),10 月在当地时间 11 月 1 日 06:30 结束。用量页面会写出当前范围覆盖的日期。
- 调用算在发生时 Key 所在的分组。把一把 Key 移到另一个分组,只有从那以后的调用算在新分组;它以前的调用留在原处。所以 API 密钥页面上一个分组的本月合计,可能不等于它下面现在列出的各把 Key 之和。
- 已撤销的 Key 留在原分组。它在撤销前的花费仍计入该分组的合计,也会出现在导出文件里。
- 删除的分组保留它的调用。这些调用在用量页面和导出文件里仍显示在它的名字下,并标注已删除;这个名字也可以再用来新建分组。
- 三处数字一致。同一个自然月,一个分组在 API 密钥页面的合计、在用量页面“本月”下的合计,以及 CSV 里该组各行之和,三者完全相同,精确到分。
常见问题
- 每个分组有自己的余额吗?没有。所有分组共用账户的同一个余额。要限制某个客户的花费,给它的分组设月度上限,或给它的每把 Key 设月度上限。
- 我的客户能登录查看用量吗?不能。分组只有你自己看得到。每把 Key 可以用 GET /v1/usage 查询自己的用量,返回结果里不包含分组。如果它的分组设了月度上限,
GET /v1/balance会告诉这把 Key 这个上限和整个分组本月已花的金额,但不包含分组的名字。 - 删除分组会怎样?由你选择:组里的 Key 继续可用,从此不属于任何分组;或者随分组一起撤销。无论哪种,它们已产生的调用都留在这个分组的名字下。
- 一把 Key 从一个客户转给另一个客户怎么办?把它移到另一个客户的分组:从那以后的调用算在新分组,以前的调用留在第一个客户名下。
- 能查看其他时间范围吗?可以:在用量页面选“自定义”,最多选 90 天。程序里可以用 GET /v1/usage 按天查询单把 Key 在同一时段的花费。
如果想用自己的工具而不是手动来创建、分组、限额和撤销客户的 Key,请使用管理 API。它的 Key 是一种独立的凭证,只能用于该 API。