文档

文档

Key 分组

给每个客户发各自的 API Key,把它们放进一个分组,随时读出任一时段里每个客户、每把 Key 花了多少,并限制每个客户一个月最多能花多少。一个账户,一个余额。

分组是账户里的一个 API Key 文件夹,比如每个客户一个:CID000001、CID000002。组里的 Key 调用 API 和其他 Key 完全一样,分组也没有自己的余额、充值或登录;分组可以设一个月度上限,按组内全部 Key 合计。一把 Key 属于一个分组,或不属于任何分组。

三步建好分组

  • 建分组。在API 密钥页面点“新建分组”,用客户名命名。
  • 把 Key 放进去。点分组标题上的“新建 Key”,直接在组里建 Key。已有的 Key 打开它的菜单,选“移到分组”。
  • 读数。API 密钥页面显示每把 Key 本自然月的花费和每个分组的合计。用量页面把同样的 Key 按分组列出,可选今日、近 7 天、近 30 天、本月、上月,或自选日期(最长 90 天)。

读出一个月并导出

在用量页面顶部选“上月”(或“本月”,或用“自定义”选日期)。在“按 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_nameKey 的名称。
key_prefixKey 的开头部分,和控制台里显示的一样。不会是完整的 Key。
key_statusactive 或 revoked。
calls这把 Key 在时间范围内的调用次数。
errors其中失败的调用次数。失败的调用不收费。
input_tokens输入 token 数,含缓存读取和缓存写入。
output_tokens输出 token 数。
cached_input_tokens输入 token 中从提示缓存读取的部分。
cache_write_tokens输入 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。