NewAPI 令牌管理：额度、分组与权限怎么设

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

NewAPI 的令牌不是一把简单的钥匙，它自带一整套限制维度：过期时间、剩余额度、是否无限额度、模型限制、IP 白名单、分组。这六项里最容易被低估的是分组——官方文档写得很明白，分组同时隔离渠道访问权限和计费倍率，也就是说改一个下拉框，既换了这把令牌能打到哪些上游，也换了这笔消费按什么系数折算。另一个高频困惑是”账户里明明还有余额，却提示额度不足”，官方 FAQ 给出的解释是令牌额度和账户额度本来就是两套独立的数，令牌那一层可以单独把你卡住。把这两件事想清楚，剩下的令牌管理基本就是照着创建对话框逐项填。

账户额度和令牌额度是两套数，别混着理解

官方 FAQ 里有一条专门的问答，标题就是”账户额度充足时为什么提示额度不足”。给出的解释分三句：令牌额度仅用于设置最大使用上限；用户可以自由设置令牌额度；请检查你的令牌额度是否充足。

这三句话背后是一个很实用的设计：账户额度是钱，令牌额度是闸门。你给某个项目发一把令牌，把它的剩余额度设成一个较小的值，那么无论账户里还剩多少，这把令牌花完自己那一份就停了。这正是把一个账户拆给多个应用、多个同事用时最需要的东西。

代价是排查时容易走弯路。看到”额度不足”，人的第一反应总是去看账户余额，看到余额还在就开始怀疑是不是计费出了 bug。按官方的说法，正确的顺序是先看令牌那一层。令牌列表页本身就把这件事摆出来了：官方文档说明列表会显示每把令牌的名称、状态、已用额度、剩余额度和过期时间——已用和剩余是分开两列的，一眼就能看出是不是这把令牌先耗尽了。

顺带说清额度这个单位本身。NewAPI 用的是内部计费单位 Quota，官方给的消耗公式是：

Quota = Group Ratio * Model Ratio * (Prompt Token Count + Completion Token Count * Completion Ratio)

分组倍率、模型倍率相乘，补全部分的 token 再单独乘一个补全倍率。也就是说同样一段对话，换个分组、换个模型，扣掉的 Quota 就不一样。倍率具体设成多少是每个部署方自己在系统设置里定的，不存在一个通用答案，这部分展开在NewAPI 分组倍率是怎么算的里。

创建令牌时那几个选项分别管什么

官方文档给的入口是：左侧边栏点”令牌”，或者直接访问 /console/token。点右上角的创建按钮弹出对话框，先起名字——官方明确建议按用途命名，举的例子是 Production、Testing 这种。这个建议不是客套话，后面查日志的时候日志筛选条件里有一项就叫”令牌名称”，名字起得含糊，几个月后你自己也认不出哪把是哪把。

对话框里可配置的选项，官方文档列成了一张表：

过期时间：设置一个到期日期；留空或者设成 -1 表示不过期（以官方文档当前版本为准）。给临时用途的令牌设一个到期日，比给自己记一条待办要靠谱得多。

剩余额度：限制这把令牌最多能消耗多少额度，超出后自动禁用。注意官方用的词是”自动禁用”而不是”暂停”——它会把令牌本身的状态改掉，所以后面要继续用得回来手动处理。

无限额度：启用之后这把令牌不受额度限制，但官方特意加了一句限定——仍然受账户总额度约束。这句限定很关键：无限额度不是无限花钱，只是把令牌那一层的闸门撤了，账户那一层的天花板还在。

模型限制：把这把令牌限制在指定的若干模型上；留空表示不限制。

IP 白名单：限制允许的来源 IP；留空表示不限制。

分组：指定这把令牌走哪个渠道分组。

填完提交，对话框会显示完整的令牌密钥。官方在这里放了一个警告框，措辞相当直白：密钥只在创建时完整显示一次，请立刻复制保存，关闭对话框后无法再次查看；令牌密钥拥有完整的 API 调用权限，不要分享给他人，也不要提交到代码仓库。

最后半句值得单独拎出来。“拥有完整的 API 调用权限”是官方对令牌密钥的原话，官方没有进一步说明它在读写或接口维度上是否有细分。所以令牌的安全边界不靠权限位，靠的是上面那几个限制项：模型限制、IP 白名单、额度上限、过期时间。这四项配齐，一把令牌泄漏出去的损失才是有界的。相关的通用做法可以参考API Key 安全管理。

分组是这套系统里权限和计费的交叉点

官方的分组管理文档开头一句话就把定位说死了：分组为不同用户隔离渠道访问权限和计费倍率，不同分组的用户只能访问分配给该分组的渠道。入口在系统设置或管理面板里的”分组”，需要管理员账号登录。

分组这个字段在三个地方出现，官方文档把它们并列列了出来：

• 用户分组：在用户管理里编辑某个用户时给他指定分组
• 令牌分组：创建令牌时指定这把令牌使用的渠道分组
• 渠道分组：添加渠道时在”分组”字段里填允许的分组名

三处配置咬合在一起才构成一条完整的通路：渠道声明自己服务哪些分组，令牌声明自己属于哪个分组，两边对上了请求才走得通。这也解释了一类看起来很怪的现象——同一个账户下两把令牌，一把能调某个模型，另一把不能。差别往往不在模型限制那一栏，而在分组不同，两把令牌落到了不同的渠道集合上。

分组字段还有一个特殊取值。官方在提示框里写道：当令牌的分组设为 auto 时，系统会按优先级顺序自动选择一个可用分组，适用于跨分组故障转移的场景。这是个很务实的设计——你不必在令牌上钉死某一个分组，让系统在多个分组之间兜底。代价是你事后看账单会发现同一把令牌的消费落在不同分组上，因为分组倍率跟着走了。

倍率这一侧还有一条优先级规则，官方文档写成了三级：用户专属倍率优先，其次是用户所属分组的倍率，最后才是系统默认倍率。也就是说给某个用户单独设过倍率，分组倍率就不再对他生效。排查”为什么两个人调同一个模型扣的不一样”，这条优先级是第一个该看的地方。

令牌能调什么管理接口，权限怎么划

NewAPI 的管理 API 文档给每个接口都标了权限级别，令牌管理这一组的标注很整齐。官方列出的接口有：

• GET /api/token/ 获取全部令牌
• POST /api/token/ 创建令牌
• PUT /api/token/ 更新令牌
• GET /api/token/{id} 获取指定令牌
• DELETE /api/token/{id} 删除令牌
• GET /api/token/search 搜索令牌
• POST /api/token/batch 批量删除令牌
• GET /api/usage/token/ 获取令牌用量

以上接口以官方文档为准。这里有一个容易被忽略的分界：上面前七个接口，官方标注的都是”需要登录（用户权限）“；只有最后那个查用量的接口标注的是”需要令牌鉴权”。

这个差别的实际含义是——你手上的那把 sk- 开头的调用令牌，可以用来查它自己的用量，但不能用来增删改令牌。要管理令牌，得走登录态。所以想写一个脚本自动轮换令牌，光有 API Key 是不够的，这条边界在动手之前就该确认清楚，否则会在鉴权上卡很久。

批量删除走的是 POST /api/token/batch 而不是 DELETE，这属于接口设计上的小意外，照抄官方路径和方法就行，别按 RESTful 直觉去猜。

官方还发布了一个用户级的 Skill，可以在编辑器里直接查模型、管令牌、看分组和余额。它的能力边界官方用一张对比表说清了：用户级 Skill 的作用域是个人的模型、令牌、余额、分组，用的是用户访问令牌；管理员那一档才覆盖全局渠道、用户、配置和日志，需要管理员访问令牌，且官方标注状态为开发中。这个 Skill 在密钥处理上有个设计值得借鉴——列出令牌时只显示掩码后的密钥，复制密钥是直接进系统剪贴板，官方的说法是真实密钥不会出现在终端输出里。自己写运维脚本时照这个思路做，能省掉一大类”密钥被日志记下来”的事故。

令牌发出去之后靠什么盯

令牌管理的后半程在日志页。官方文档说明入口是左侧边栏的”日志”或直接访问 /console/log，普通用户只能看到自己的调用记录。列表里每一行是一次 API 调用，显示调用时间、使用的模型、消耗的 token 数、扣除的额度和调用状态。

筛选条件里明确有”令牌名称”这一项，可以选择或输入。这就是前面强调按用途命名的兑现点——一把令牌一个用途，日志按令牌名一筛，某个应用这段时间花了多少、失败了几次，直接就出来了。配合”仪表盘”（/console）里按天的调用量和额度消耗趋势图，基本能定位到是哪天、哪个应用开始不对劲。管理员视角的日志列表还会多出”用户名”和”渠道名称”两列，能看到全部用户的调用记录。

把令牌交到客户端手上也有现成的路子。官方文档里以某个翻译客户端为例描述过这个流程：在令牌管理页选中要用的令牌，点击聊天按钮旁边的下拉选项，选中目标客户端，就会跳转过去并自动填好 API 地址和 API Key。这类跳转由系统的聊天设置统一配置，可用的变量是 {key}（替换为密钥）和 {address}（替换为服务器地址，末尾不带 / 和 /v1）。自己部署时如果发现跳过去的客户端连不上，先看这两个变量拼出来的地址对不对。

落地时的几个顺序建议

按官方文档的信息组织，一条不容易返工的路径大致是这样：先在系统设置里把分组和倍率定下来，再给渠道填上允许的分组，最后才发令牌。反过来先发令牌、后调分组，那些已经发出去的令牌会在你调整倍率的当天悄悄换一个价格口径，而持有令牌的人对此毫无察觉。

几个容易栽的地方，集中在这里：

• 看到”额度不足”先查令牌额度，不是账户余额。官方 FAQ 明确说这是两套数。
• 无限额度不等于无限。官方原文括号里那句”仍受账户总额度约束”是硬约束。
• 密钥只显示一次。没存下来就只能重新建一把，没有找回入口。
• 模型限制和分组解决的不是同一个问题。模型限制是在这把令牌能达到的范围内再收窄；分组决定的是这把令牌能达到哪些渠道。两者都留空，令牌的能力面就是账户能力面的全集。
• 超额自动禁用后需要人工介入。如果这把令牌喂着线上服务，超额那一刻就是一次故障，额度上限该配合监控一起用，具体做法见API 调用成本监控。

如果你还没把服务跑起来，令牌这一层可以先放放——先按NewAPI 部署教程把实例立起来，走通一次调用之后再回头设计分组和令牌的划分方式，那时候你对自己到底需要几个隔离维度会有更实际的判断。