接口概述
令牌管理接口让你用程序完成 API Key 的全生命周期管理,不必逐个在控制台点击。 最常见的场景是批量发放:给团队成员、给下游客户、给不同项目各发一把 Key, 并分别限制能花多少钱、能用哪些模型、用到什么时候。 配合定时任务,还能做到每把 Key 每天限额、次日自动恢复。额度限制
remain_quota 设定这把 Key 最多能消费多少模型限制
models 设定白名单,调用名单外的模型直接被拒有效期限制
expired_time 设定到期时间,到点自动失效只需要建一两把 Key 的话,直接用控制台更快,见 如何创建 KEY。
本接口面向需要自动化发放、定期轮换、或把 Key 管理接入自有系统的场景。
如何获取个人访问令牌
令牌管理接口用个人访问令牌认证(nap_ 开头),与 API Key 不是一回事。
1
打开个人访问令牌
访问
api.apiyi.com/account/profile 个人中心,在「账户选项」里点击 个人访问令牌 → 创建令牌2
按用途勾选「模型密钥」权限
三项权限相互独立,只勾用得到的:
批量发 Key 的脚本三项都要勾;只做用量巡检的脚本勾「读取」即可。
3
设置到期时间与 IP 白名单
到期时间默认 30 天,建议选久一点。发 Key 的脚本跑在固定 IP 的服务器上时,强烈建议设置 IP 白名单(创建后不能修改,可以先不填调通,再新建一把带白名单的正式令牌)

端点一览
所有端点的认证方式相同:Authorization 请求头填个人访问令牌,Bearer 前缀可加可不加。
基础地址为
https://api.apiyi.com。
创建令牌
请求示例
请求字段
响应示例
获取 Key 明文
- 需要个人访问令牌勾选 模型密钥 · 查看密钥,否则返回 403
ACCESS_TOKEN_SCOPE_DENIED - 返回的
key不含sk-前缀,实际使用时需要自己拼上,即上例中真正的 API Key 是sk-K1RPzapu… - 拿到后立即保存并通过安全渠道分发,不要把响应体留在日志文件里
批量创建
服务端没有批量创建接口 —— 在请求体里传count 之类的参数不会生效,仍然只创建一把。
批量发放的做法是在客户端循环调用创建接口。
- Python
- Node.js
- cURL
三重限制怎么用
额度限制
remain_quota 是这把令牌能消费的额度上限,换算关系与余额查询 一致:
换算规则
500,000 额度 = $1.00 美金 (USD)
remain_quota: 5000000 且
unlimited_quota: false。用量可以从令牌的 used_quota 字段读取。
remain_quota 是一次性的总额度,用完不会自动恢复。要「每天限额」,见下文场景:每把 Key 每天限额,次日自动恢复。
模型限制
models 是逗号分隔的白名单。设置后,用这把 Key 调用名单外的模型会被直接拒绝:
models 表示不限制。
有效期限制
expired_time 是 Unix 秒时间戳,-1 表示永不过期。例如发一把 30 天后失效的 Key:
查询令牌
更新令牌
场景:每把 Key 每天限额,次日自动恢复
企业把 Key 发给工作流、成员或下游项目时,常见的诉求是「每把 Key 每天最多花 $5,第二天自动恢复」, 这样某个工作流跑飞了,损失也只限于一天的额度。 平台目前没有内置「每日额度」字段,但用上面的更新接口加一个每天零点跑一次的定时任务就能做到: 每天把这几把 Key 的remain_quota 改回当日上限。Key 本身不变,团队成员不用换 Key,
当天额度用完后调用会被拒绝(不扣费),零点重置后自动恢复。
1
准备个人访问令牌
勾选 模型密钥 · 读取 和 模型密钥 · 写入 即可,不需要「查看密钥」。
脚本跑在固定 IP 的服务器上时,建议给这把令牌设置 IP 白名单。
2
列出要限额的 Key 及每日上限
用「查询令牌」接口查到各 Key 的
id,填进下面脚本的 DAILY_BUDGET_USD。3
每天 00:00 (UTC+8) 运行一次脚本
用 cron、云函数定时触发器或任意调度器都可以,见下文。
重置脚本
- 防重复:同一天内重复触发(调度器补跑、手动重跑)不会再发一次额度
- 结转超支:额度是软上限(见下方说明),昨天超出的部分从今天扣回,长期看每天平均不超过上限;
不需要的话把
CARRY_OVERDRAFT改成False - 输出昨日花费:每次运行打印各 Key 上一周期花了多少,日志留着就是一份简易日报
定时运行
把令牌写进只有自己可读的环境变量文件,再用 cron 每天触发:TZ。
使用前要知道的几点
- 重置是覆盖,不是累加:没用完的额度不会滚到第二天。另外,在控制台手动改了这些 Key 的额度,下次重置时会被覆盖
- 零点前后的在途请求:零点前发出、零点后才结束的请求,费用可能记进新的一天,金额一般很小
- 脚本没跑时 Key 会停在用完状态:结果是暂时不能调用,不会多花钱。建议给定时任务加失败告警
- 账户余额仍是总闸:各 Key 的每日额度加起来超过账户余额时,余额先耗尽,所有 Key 都会停
- 单个 Key 想临时多给点:直接用更新接口把它当天的
remain_quota调高,次日照常重置回上限
禁用与删除
禁用(保留记录)
禁用后该 Key 立即失效,再用它调用模型会返回 401,但令牌记录和历史用量仍然保留。删除(不可恢复)
删除是不可恢复操作。如果只是想临时停用,用上面的禁用方式,历史用量记录会保留下来便于对账。
常见问题
创建时返回的 key 怎么直接不能用?
创建时返回的 key 怎么直接不能用?
创建接口返回的
key 是打码后的值(中间是一串 *),不能直接用。用返回的 id 调
POST /api/token/{id}/key 取明文(需勾「查看密钥」权限),再在前面拼上 sk-。
早期脚本若直接用创建响应里的 key,换成个人访问令牌时需要补上这一步。为什么我建出来的令牌一调用就提示额度不足?
为什么我建出来的令牌一调用就提示额度不足?
最可能的原因是创建时既没传
remain_quota,也没把 unlimited_quota 设为 true ——
两者的缺省组合会建出一把额度为 0 的令牌。重新创建时显式指定其中之一即可。传了 model_limits 或 allow_ips 为什么没有效果?
传了 model_limits 或 allow_ips 为什么没有效果?
这两个字段(以及
model_limits_enabled)当前不生效,传入不会报错但也不会落库。
限制可用模型请使用 models 字段;限制来源 IP 目前需要在你自己的服务侧实现。能一次创建多把令牌吗?
能一次创建多把令牌吗?
服务端没有批量创建接口,在请求体里传
count 之类的参数不会生效。
批量发放请在客户端循环调用创建接口,参考上面「批量创建」一节的示例。一个账号最多能有多少把令牌?
一个账号最多能有多少把令牌?
单个用户最多 1000 个令牌,已禁用但未删除的也计入这个总量。达到上限后创建接口会失败,
需要先删除不再使用的令牌。轮换 Key 时记得走到「删除」这一步,只禁用不删除会占着名额。
能不能限制每把 Key 每天的花费,第二天自动恢复?
能不能限制每把 Key 每天的花费,第二天自动恢复?
平台没有内置「每日额度」字段,但可以用定时任务实现:每天 00:00 (UTC+8) 调更新接口,
把这些 Key 的
remain_quota 改回当日上限。Key 不用换,当天用完会被拒绝且不扣费,次日自动恢复。
完整脚本与注意事项见上文场景:每把 Key 每天限额,次日自动恢复。更新令牌后其他字段被清空了?
更新令牌后其他字段被清空了?
更新接口需要传完整对象。先
GET 拿到完整对象,改完再整个 PUT 回去,
不要只传要改的那几个字段。禁用和删除有什么区别?
禁用和删除有什么区别?
禁用(
status: 2)后 Key 立即失效,但令牌记录与历史用量保留,可以随时改回 1 恢复。
删除是不可恢复的,记录一并移除。临时停用建议用禁用。怎么知道每把 Key 各自花了多少钱?
怎么知道每把 Key 各自花了多少钱?
令牌对象的
used_quota 字段就是这把 Key 的累计消费(÷ 500,000 = 美元)。
需要按时间段拆分或看每次调用的明细,去控制台日志页按令牌名筛选,
见如何查看我的调用记录。注意事项
操作建议
- 批量创建时建议在循环里加适度间隔,避免瞬时并发过高
- 给每把 Key 起有意义的
name(如team-alice、prod-webhook),便于后续在日志里按token_name归因 - 定期轮换:新建 Key → 切流量 → 禁用旧 Key 观察一段时间 → 确认无调用后再删除
相关文档
- 如何查看我的调用记录 —— 在控制台查每把 Key 的调用明细与扣费
- 余额查询 API —— 查账号剩余额度
- 如何创建 KEY —— 控制台手动创建
- 令牌与分组 —— 分组的作用与选择