跳转到主要内容

接口概述

令牌管理接口让你用程序完成 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 白名单(创建后不能修改,可以先不填调通,再新建一把带白名单的正式令牌)
创建个人访问令牌:名称、到期时间、IP 白名单与权限
勾了「写入」和「查看密钥」的令牌能创建出可以调用模型的 API Key,请像保管账号密码一样保管它。个人访问令牌本身不能调用模型,但它能发出可以调用模型的 Key。因此这类令牌务必设置 IP 白名单、 存进密钥管理工具而不是写在代码里,不要提交进代码仓库,并在到期前及时换新。
旧系统令牌计划于 2026-11-11 (UTC+8) 停用。 原来在「账号选项 - 系统令牌」生成的 AccessToken 在此之前照常可用,之后会返回 401 ACCESS_TOKEN_LEGACY_RETIRED。 平台会视使用情况决定是否延期,建议尽早换成个人访问令牌。换令牌时请同时检查脚本:新版创建接口返回的 key 已打码,取明文要另调一次 POST /api/token/{id}/key,见下文。 详见 什么是个人访问令牌?

端点一览

所有端点的认证方式相同:Authorization 请求头填个人访问令牌,Bearer 前缀可加可不加。 基础地址为 https://api.apiyi.com。

创建令牌

请求示例

请求字段

unlimited_quota 缺省为 false,而 remain_quota 缺省为 0 —— 两者一起缺省时会建出一把 额度为 0、无法使用的令牌。要么显式给 remain_quota 赋值,要么把 unlimited_quota 设为 true。
模型白名单请使用 models 字段。响应结构里还存在 model_limits、model_limits_enabled、allow_ips 三个字段, 传入它们不会报错(接口仍返回 200),但当前不会生效 —— 回读时这些字段仍为空。 需要限制可用模型请使用 models,需要限制来源 IP 请在自己的服务侧实现。

响应示例

响应里的 key 是打码后的值,不能直接使用。 要拿到明文,用响应里的 id 再调一次获取明文接口。

获取 Key 明文

  • 需要个人访问令牌勾选 模型密钥 · 查看密钥,否则返回 403 ACCESS_TOKEN_SCOPE_DENIED
  • 返回的 key 不含 sk- 前缀,实际使用时需要自己拼上,即上例中真正的 API Key 是 sk-K1RPzapu…
  • 拿到后立即保存并通过安全渠道分发,不要把响应体留在日志文件里

批量创建

服务端没有批量创建接口 —— 在请求体里传 count 之类的参数不会生效,仍然只创建一把。 批量发放的做法是在客户端循环调用创建接口。
单个用户最多 1000 个令牌。 这是账号级别的总量上限,包含已禁用但未删除的令牌。 达到上限后创建接口会失败,需要先删除不再使用的令牌腾出名额。批量发放前先用 GET /api/token/?p=0&page_size=100 翻页统计当前数量, 把「新建 Key → 切流量 → 禁用旧 Key → 确认无调用后删除」中的最后一步真正执行到位, 不要只禁用不删除,否则轮换几轮就会撞到上限。

三重限制怎么用

额度限制

remain_quota 是这把令牌能消费的额度上限,换算关系与余额查询 一致:

换算规则

500,000 额度 = $1.00 美金 (USD)
例如给下游客户发一把最多消费 $10 的 Key,就设 remain_quota: 5000000 且 unlimited_quota: false。用量可以从令牌的 used_quota 字段读取。 remain_quota 是一次性的总额度,用完不会自动恢复。要「每天限额」,见下文场景:每把 Key 每天限额,次日自动恢复。

模型限制

models 是逗号分隔的白名单。设置后,用这把 Key 调用名单外的模型会被直接拒绝:
返回 HTTP 403,不产生扣费。不传 models 表示不限制。

有效期限制

expired_time 是 Unix 秒时间戳,-1 表示永不过期。例如发一把 30 天后失效的 Key:

查询令牌

关键字段:

更新令牌

更新接口需要传完整对象,不是增量更新(patch)。正确做法是:先 GET 拿到令牌的完整对象 → 修改需要变更的字段 → 把整个对象 PUT 回去。 只传要改的那几个字段会把其余字段清空。

场景:每把 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 每天触发:
想按别的时区划分「一天」,同时改 cron 时间和脚本里的 TZ。

使用前要知道的几点

额度是软上限,不是精确的刹车。 额度检查发生在请求开始时,几个并发请求可能同时通过检查, 单次很贵的请求(视频、4K 出图、超长上下文)也可能一次就越过上限,余额会被打成负数。 并发越高、单价越高,超出越多。脚本的「结转超支」会把超出部分从次日扣回; 如果某些 Key 不能有任何超支,就在自己的服务侧控制它的并发数,或者用 models 白名单把高单价模型排除在外。
  • 重置是覆盖,不是累加:没用完的额度不会滚到第二天。另外,在控制台手动改了这些 Key 的额度,下次重置时会被覆盖
  • 零点前后的在途请求:零点前发出、零点后才结束的请求,费用可能记进新的一天,金额一般很小
  • 脚本没跑时 Key 会停在用完状态:结果是暂时不能调用,不会多花钱。建议给定时任务加失败告警
  • 账户余额仍是总闸:各 Key 的每日额度加起来超过账户余额时,余额先耗尽,所有 Key 都会停
  • 单个 Key 想临时多给点:直接用更新接口把它当天的 remain_quota 调高,次日照常重置回上限

禁用与删除

禁用(保留记录)

禁用后该 Key 立即失效,再用它调用模型会返回 401,但令牌记录和历史用量仍然保留。

删除(不可恢复)

批量删除同样在客户端循环即可:
删除是不可恢复操作。如果只是想临时停用,用上面的禁用方式,历史用量记录会保留下来便于对账。

常见问题

创建接口返回的 key 是打码后的值(中间是一串 *),不能直接用。用返回的 id 调 POST /api/token/{id}/key 取明文(需勾「查看密钥」权限),再在前面拼上 sk-。 早期脚本若直接用创建响应里的 key,换成个人访问令牌时需要补上这一步。
最可能的原因是创建时既没传 remain_quota,也没把 unlimited_quota 设为 true —— 两者的缺省组合会建出一把额度为 0 的令牌。重新创建时显式指定其中之一即可。
这两个字段(以及 model_limits_enabled)当前不生效,传入不会报错但也不会落库。 限制可用模型请使用 models 字段;限制来源 IP 目前需要在你自己的服务侧实现。
服务端没有批量创建接口,在请求体里传 count 之类的参数不会生效。 批量发放请在客户端循环调用创建接口,参考上面「批量创建」一节的示例。
单个用户最多 1000 个令牌,已禁用但未删除的也计入这个总量。达到上限后创建接口会失败, 需要先删除不再使用的令牌。轮换 Key 时记得走到「删除」这一步,只禁用不删除会占着名额。
平台没有内置「每日额度」字段,但可以用定时任务实现:每天 00:00 (UTC+8) 调更新接口, 把这些 Key 的 remain_quota 改回当日上限。Key 不用换,当天用完会被拒绝且不扣费,次日自动恢复。 完整脚本与注意事项见上文场景:每把 Key 每天限额,次日自动恢复。
更新接口需要传完整对象。先 GET 拿到完整对象,改完再整个 PUT 回去, 不要只传要改的那几个字段。
禁用(status: 2)后 Key 立即失效,但令牌记录与历史用量保留,可以随时改回 1 恢复。 删除是不可恢复的,记录一并移除。临时停用建议用禁用。
令牌对象的 used_quota 字段就是这把 Key 的累计消费(÷ 500,000 = 美元)。 需要按时间段拆分或看每次调用的明细,去控制台日志页按令牌名筛选, 见如何查看我的调用记录。

注意事项

个人访问令牌不是 API Key,两者不能互换
  • API Key(sk- 开头)用于 /v1/* 推理端点
  • 个人访问令牌(nap_ 开头)用于 /api/* 管理端点,不能调用模型
报错对照:401 ACCESS_TOKEN_LEGACY_RETIRED 是仍在用已停用的旧系统令牌; 401 This access token may not be used from the current IP address. 是来源 IP 不在令牌白名单内; 403 ACCESS_TOKEN_SCOPE_DENIED 是令牌没勾这个接口需要的权限(见上方端点一览)。
妥善保管明文 Key「获取 Key 明文」接口返回的是可以直接调用模型的 Key。请注意:
  • 不要把包含 key 的原始响应写进日志文件或提交进代码仓库
  • 分发给团队成员时使用安全渠道,不要通过聊天群直接发送
  • 这段明文不带 sk- 前缀,常见的密钥扫描工具可能扫不出来,不要依赖自动化检查兜底
操作建议
  • 批量创建时建议在循环里加适度间隔,避免瞬时并发过高
  • 给每把 Key 起有意义的 name(如 team-alice、prod-webhook),便于后续在日志里按 token_name 归因
  • 定期轮换:新建 Key → 切流量 → 禁用旧 Key 观察一段时间 → 确认无调用后再删除

相关文档