NewAPI 怎么用：渠道、令牌与分组的基本概念

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

NewAPI 怎么用，说到底就是三个对象的关系：渠道（Channels）向上接厂商，API 令牌（Tokens）向下发给调用方，用户分组（Group）是把这两头对起来的那把钥匙。渠道决定”请求能落到哪家上游”，令牌决定”谁能调、能调多少、能调哪些模型、能从哪个 IP 调”，分组决定”这个令牌的请求被允许落到哪一批渠道上”，并且同时决定这批请求按什么倍率扣额度。三者任意一处没对齐，最典型的症状就是官方 FAQ 里那句 No available channels——而官方给出的排查顺序恰好就是这三个概念：先看用户分组设置，再看渠道分组设置，最后看渠道的模型设置。把这条链路想清楚，后台里那一堆配置项就能各归其位了。

先把三个对象的位置摆清楚

官方文档对渠道的定义很直接：渠道是连接 AI 供应商的核心配置单元，一个渠道对应一家供应商的一个 API Key。管理员账号登录后从左侧栏进入渠道页，列表里能看到每个渠道的名称、类型、状态（绿色为启用、红色为禁用）、响应时间和已用额度。

令牌的定位是 API 凭证。文档里写得很清楚：每个令牌都可以独立配置自己的权限范围和额度上限。令牌列表展示的是名称、状态、已用额度、剩余额度和过期时间。

分组的作用被官方概括为一句话：为不同用户隔离渠道访问权限与计费倍率，不同分组的用户只能访问分配给该分组的渠道。注意这句话里塞了两件事——权限隔离和计费倍率。这是 NewAPI 里最容易被低估的一个设计：分组不是单纯的标签，它同时是访问控制边界和计费系数的挂载点。

所以配置顺序天然是：先建渠道（把上游接进来），再规划分组（把渠道按可见性切开），最后签发令牌（把使用权发出去）。反过来先发令牌再补渠道，多半会撞上无可用渠道。

在动手接上游之前，官方在渠道页放了一条醒目的合规提示：上游渠道必须是部署方合法拥有或获得授权的账号、API Key、模型服务或企业合同；负载均衡、自动故障转移、加权随机、多 Key 管理这些能力是用于高可用与企业多账号管理的，使用时应当遵守上游服务条款、平台规则与监管要求。这条不是客套话，自建网关的合规风险基本都压在这一句上。

渠道怎么配：那几个高级选项才是重点

新增渠道的主流程不复杂——点渠道列表右上角的”添加渠道”，选供应商类型（例如 OpenAI、Claude、Gemini），填渠道名称和 API Key，在模型列表里勾选这个渠道支持的模型（也可以点”填入默认模型”自动带出来），最后提交。

真正值钱的是展开”高级配置”之后那几项，官方文档给了一张选项说明表：

• Base URL：自定义端点地址，用于代理或自部署场景；
• 优先级（Priority）：数值越大优先级越高，越先被选中；
• 权重（Weight）：同优先级渠道之间随机分配的权重；
• 模型映射（Model Mapping）：把用户请求的模型名映射成实际模型名，填 JSON；
• 参数覆盖（Parameter Override）：强制覆盖某些请求参数，填 JSON；
• 自动禁用（Auto Disable）：开启后，连续失败会自动把渠道禁用掉。

优先级和权重这一对经常被搞混，官方 FAQ 专门解释过：优先级是分层的，高优先级的渠道会先被使用；权重只在同优先级的渠道之间起作用，请求按权重比例分配。也就是说，如果你把两个渠道设成不同优先级，权重根本不会生效——想做流量按比例分摊，必须先让它们的优先级相同。

参数覆盖还有个容易被忽略的边界：官方明确写了这个功能只能用于兼容合法上游接口格式、企业网络兼容和请求规范化。它支持简单覆盖模式（直接给出要覆盖的字段和值，系统把这些字段合并进原请求）和高级操作模式（用 operations 数组表达带条件逻辑的操作），操作类型包括 set、delete、append、prepend、replace、regex_replace、to_lower、to_upper 等，具体取值范围以官方文档当前版本为准。

渠道配完可以点行内的”测试”按钮发一次测试请求，弹窗会返回响应时间和成功失败状态，列表顶部也有”测试所有渠道”做批量检查。多选渠道行还会在页面顶部弹出批量操作栏，支持批量启用、批量禁用和批量打标签。

如果一家上游你手里有多把 Key，不必建多个渠道。官方提供了多 Key 模式：在渠道编辑弹窗里找到”多 Key 管理”，逐个添加 Key，再选一种轮询模式——顺序轮询（依次使用每把 Key）或加权随机（按权重随机选）。文档特别说明，失败的 Key 会被自动跳过，恢复后会重新启用。这一层与渠道级的自动禁用是两件事：多 Key 是渠道内部的容错，自动禁用是渠道整体的熔断。

部署环节的准备工作可以对照 NewAPI 部署教程 一起看，渠道配置是部署跑通之后的第一步。

令牌怎么建：六个选项决定它有多大权力

进令牌页（左侧栏”令牌”）点”创建令牌”，先给个按用途命名的名字——官方举的例子就是 Production、Testing 这种。然后是六个配置项，官方文档逐项给了说明：

• 过期时间：设定到期日期，留空或设为 -1 表示不过期（以官方文档当前版本为准）；
• 剩余额度：限制这个令牌最多能消耗多少额度，超出后自动禁用；
• 无限额度：开启后该令牌不受自身额度限制，但仍然受账户总额度约束；
• 模型限制：限定这个令牌只能调用指定模型，留空表示不限制；
• IP 白名单：限定允许的来源 IP，留空表示不限制；
• 分组：指定这个令牌使用哪个渠道分组。

提交之后弹窗会显示完整的令牌密钥，官方在这里挂了一条警告：密钥只在创建时完整展示一次，关闭弹窗后就看不到了，必须立刻复制保存；令牌密钥拥有完整的 API 调用权限，不要分享给他人，也不要提交到代码仓库。这条和通用的 API 密钥安全管理 是一回事，只是自建网关多了一层——你签发的令牌一旦泄漏，泄漏的是你自己那份上游账单。

“无限额度”这个开关的措辞值得咬一下：它写的是仍受账户总额度约束。也就是说令牌额度和账户额度是两道独立的闸，无限额度只关掉了令牌这一道。这直接解释了官方 FAQ 里那个高频问题——账户额度明明充足，为什么提示额度不足？答案是令牌额度和账户额度本来就是分开的，令牌额度只用来设置使用上限的天花板，用户可以自由设定，报额度不足时应该先去查令牌那一侧的额度够不够。

分组：同时管权限和倍率的那个交叉点

分组之所以绕，是因为它要在三个地方各填一次，官方文档把这三处并列写了出来：

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

三处填的是同一套分组名，请求要跑通，就得让令牌所属的分组落在渠道允许的分组集合里。文档还给了一个特殊取值：当令牌的分组设为 auto 时，系统会按优先级顺序自动选择一个可用分组，适用于跨分组故障转移的场景。

计费那一侧，分组倍率是三层倍率体系里的一层。官方给出的额度计算公式是分组倍率乘模型倍率，再乘上”输入 token 数加输出 token 数乘补全倍率”这一整块；生效关系官方在 FAQ 里也复述过一次：用户实际倍率等于模型倍率乘分组倍率。倍率还有优先级顺序——用户专属倍率优先于分组倍率，分组倍率优先于系统默认倍率。具体倍率数值由每个部署方自己设定，这里不给任何数字，机制部分可以看 NewAPI 分组倍率怎么算。

限流也挂在分组上。官方的分组限流配置是一段 JSON，键是分组名，值是一个包含两个数字的数组，第一个是每分钟请求上限、第二个是每小时请求上限，设为 0 表示不限制；同一分组内的所有用户共享这份限流配置。这与全局限流是两层——全局那层是按单个 IP 算每分钟、每小时、每天的请求上限。想理解这些计数窗口本身的含义，可以对照 RPM 与 TPM 限流机制 那篇。

配完之后怎么验证能用

官方给的顺序是先用内置的 Playground 试，再接代码。Playground 在左侧栏，作用是不写代码直接和模型对话，官方对它的定位就是快速验证令牌是否可用：选模型、输入消息、发送、右侧看回复。这一步能把”令牌配错了”和”客户端配错了”两类问题分开。

API 地址从平台首页拿：首页中部有 API Base URL 展示区，点复制按钮拿到地址，之后在客户端或代码里当作 base_url 用，配上你的令牌即可。官方对整个接入方式的概括是一句话——把 OpenAI 的 base_url 换成平台地址，把平台签发的令牌当作 api_key，就能开始调用。文档给的示例覆盖了三种格式：Python 的 OpenAI SDK、Claude 原生格式（走 /v1/messages，带 x-api-key 和 anthropic-version 头）、Gemini 原生格式（走 /v1beta 路径，key 放在查询参数上）。

兼容端点方面，官方列了一张表，包含对话补全、文本补全、向量化、图像生成、图像编辑、语音转文本、文本转语音、重排序、Responses 格式、Realtime（WebSocket）以及模型列表这些路径，具体路径与支持范围以官方文档为准。这张表的实际用途是判断你手上的客户端能不能直接对接——如果它只打对话补全那一条路径，基本不会有兼容问题。

最容易卡住的三处

No available channels（无可用渠道）：官方给的三步排查是用户分组设置、渠道分组设置、渠道模型设置。前两步是分组没对齐，第三步是这个渠道压根没勾选被请求的那个模型。

倍率或价格未配置：渠道测试会直接报出来，官方的处理建议是去”系统设置 - 运营设置 - 模型倍率设置”里检查该模型的倍率或价格有没有配，或者在运营设置里开启自用模式。文档还说明了未配置倍率的模型有两种走向：自用模式下套用系统默认倍率，计费模式下直接提示未配置；管理界面里也会把未配置的模型标出来。

当前分组负载已饱和：官方对这条错误的解释很干脆——上游渠道返回了 429（请求过多）。也就是说这不是你本地配置的问题，是上游在限流，方向应该转向加渠道、调优先级权重或者启用多 Key，而不是去改本地的分组设置。

还有一条容易被误判的：渠道测试报 invalid character '<' looking for beginning of value。官方解释是返回值不是合法 JSON 而是一个 HTML 页面，最可能的原因是部署站点的 IP 或代理节点被 CloudFlare 拦了。看到这个报错别去查模型配置，先查网络出口。

收尾：先把分组规划想好再发令牌

这套设计里最值得提前想清楚的是分组。它既是访问边界又是计费系数，还挂着限流配置，一旦令牌大批签发出去再改分组划分，改的就不只是权限，连账单口径和限流策略都会一起变。

比较省事的做法是在建第一个渠道之前就把分组名定下来——按团队分、按环境分、还是按成本中心分，选一种并写进文档；渠道建的时候直接填分组，令牌签发的时候直接选分组。计费与用量的核对则统一去用量日志里看，官方说明那里能看到每次调用所用的令牌分组、模型和消耗，普通用户看自己的，管理员能看到别人的。这个字段组合正好和上面三个对象一一对应，是核账时最快的入口。