NewAPI 特性与配置：OneAPI fork 的进阶功能详解

2026-07-27

NewAPI 是 OneAPI 的活跃 fork，保留了 OneAPI 的所有基础能力，并在渠道管理、计费灵活性、用户系统和多模态支持上做了显著扩展。如果你已经熟悉 OneAPI，本文聚焦 NewAPI 的差异点和进阶特性。

NewAPI vs OneAPI 功能对比

功能维度	OneAPI	NewAPI
基础聚合	支持	支持（继承）
OpenAI 兼容接口	支持	支持（继承）
渠道类型数	较多	更多（含 Midjourney、Suno 等）
Midjourney 支持	不支持	原生支持（绘图任务管理）
计费模式	按 token 倍率	按 token 倍率 + 按次计费（绘图等）
用户注册	邀请码/邮件	更多注册方式（微信登录等）
UI 风格	经典风格	更现代的界面
令牌分组	基础	支持用户组与差异化定价
聊天界面	无	内置简单聊天页面（可选开启）
社区活跃度	非常高	活跃（国内社区为主）

NewAPI 的核心进阶特性

1. 用户组与差异化定价

NewAPI 支持将用户划分为不同组（如”普通用户”、“会员用户”、“企业用户”），每个组对不同模型的倍率不同：

普通用户组：
  gpt-4o 倍率 = 1.5（即 OpenAI 定价的 1.5 倍）
  gpt-4o-mini 倍率 = 1.2

会员用户组：
  gpt-4o 倍率 = 1.2
  gpt-4o-mini 倍率 = 1.0

这让 NewAPI 更适合做面向最终用户的 AI API 分发平台，差异化定价直接在后台配置，无需改代码。

倍率这东西看着简单，配置时最容易翻车的地方是”新增模型忘记单独设倍率”——NewAPI 的倍率继承规则是：某个模型没有在渠道级或分组级显式设置倍率时，会退回到全局默认倍率（通常是 1.0，或者你在系统设置里改过的那个值）。我见过真实的案例：某团队上了 gpt-4o-mini 之后忘记给会员组单独配倍率，结果会员组反而比普通用户组贵——因为普通组给 gpt-4o-mini 设了 0.8 的优惠倍率，会员组没设，退回默认的 1.0。这种问题不会报错，只会在月底对账时冒出来：“这个月成本怎么比预期高一截”。建议做法：每次上新模型，“渠道”和”令牌分组”两处的倍率表都要过一遍，而不是改了一处就以为完事。另外要分清楚倍率影响的是什么——它只决定用户额度按什么速度被扣减，不影响你实际付给上游的账单：如果上游用的是官方定价，倍率设成 1.5 就是你在这单业务上赚 50% 的差价，设成 0.8 则是你在自己贴钱补贴用户，这个换算关系最好写进你自己的运营手册，不要指望前端用户或客服自己心算明白。

2. 按次计费（Midjourney、绘图等）

对按图收费的服务（Midjourney、Flux、Suno 等），不能简单用 token 倍率，NewAPI 引入”按次计费”模式：

Midjourney Imagine（文生图）：每次扣减 X 点
Midjourney Upscale（放大）：每次扣减 Y 点
Suno 生成歌曲：每次扣减 Z 点

用户在个人中心查看余额（以”点”或自定义货币单位显示），管理员在后台为用户充值。

点数扣减这套东西看着直观，实际运营时最容易踩的坑是”点数和实际成本脱钩”。举个例子：如果 Midjourney Upscale 单次的点数设置得比 Imagine 便宜太多，用户会反复放大同一批图去”薅”你的额度——放大任务的计算成本其实并不比生成低多少。给按次计费定点数之前，先查清楚你接的这个 MJ 代理渠道本身按什么方式跟你结算：如果它也是按次计费，你的点数定价至少要覆盖这个成本再加上毛利；如果它是按 GPU 时长计费，就得估算平均一次任务耗时再折算成本，不要拍脑袋定数字。另一个容易漏掉的地方是退款逻辑：任务提交后如果最终失败（渠道超时、内容被上游审核拦截），NewAPI 默认不一定会自动退回点数，这取决于你接入的具体版本和代理实现。稳妥的做法是先在测试环境故意提交一个会被拦截的 prompt，观察点数是否退回，再决定要不要自己在后台加一套人工退款流程。

3. Midjourney 原生代理

NewAPI 内置 Midjourney 任务队列管理：

POST /mj/submit/imagine
{
  "prompt": "a futuristic city at sunset, cyberpunk style"
}

# 轮询任务状态
GET /mj/task/{task_id}/fetch

响应结构与主流 Midjourney 代理服务兼容，前端直接对接 NewAPI 即可，无需额外搭建 MJ 代理。

实际跑起来你会遇到的头号问题是任务卡在 pending 状态迟迟不出图。先别怀疑 NewAPI 本身，这条链路的责任划分是：前端提交 → NewAPI 转发给 MJ 代理 → MJ 代理转发给真实的 Midjourney 账号池 → 排队生成 → 逐层回传结果。卡住的地方九成在”账号池排队”或者”代理服务本身的回调没对上”。排查顺序：先用 GET /mj/task/{task_id}/fetch 直接查任务状态——如果返回状态一直停在 SUBMITTED 不变，说明代理那边根本没收到任务或者代理服务本身挂了，去查代理服务的日志而不是 NewAPI 的日志；如果状态是 IN_PROGRESS 但进度长时间不动，通常是账号池在排队，这是 MJ 账号池本身的限制，加账号或者提前告知用户高峰期需要排队是唯一解法。轮询频率也有讲究：前端如果每秒轮询一次 fetch 接口，账号量一大，这个轮询流量本身就会给你的服务器和数据库带来额外压力，实践中 2-3 秒一次的轮询间隔、任务完成后立刻停止轮询，是比较务实的做法。

4. 渠道测试与自动禁用

NewAPI 支持定时自动测试渠道可用性：

配置：每 5 分钟测试所有渠道
行为：连续失败 3 次 → 自动禁用渠道 + 发送告警
恢复：管理员手动检查后重新启用

相比 OneAPI 的被动容灾（请求时才发现失败），NewAPI 的主动探活让渠道状态更实时。

这里有个容易被忽略的坑：测试模型选错，会让一个其实健康的渠道被误判下线。比如你选了 gpt-4o 作为测试模型，但某个渠道只开通了 gpt-3.5-turbo 的额度，测试请求必然报模型不存在，NewAPI 会把这当成渠道故障，连续测试失败几次后自动禁用——但这个渠道其实好好的，只是不支持你选的测试模型。所以测试模型要选”这个渠道组里所有渠道都确定支持”的最低成本模型，而不是随手选一个你自己常用的模型。另外，如果测试模型本身是收费的，5 分钟测一次、渠道数量一多，这笔测试调用的费用长期看也不是零，值不值得拉长间隔，取决于你的渠道规模和对实时性的要求——渠道少的话把测试间隔拉长到 15-30 分钟通常更划算。

部署方式

NewAPI 与 OneAPI 使用相同的 Docker 部署模式：

docker pull calciumion/new-api:latest

docker run -d \
  --name new-api \
  -p 3000:3000 \
  -v /data/new-api:/data \
  -e TZ=Asia/Shanghai \
  -e SQL_DSN="root:password@tcp(mysql-host:3306)/newapi?charset=utf8mb4" \
  -e REDIS_CONN_STRING="redis://localhost:6379" \
  --restart always \
  calciumion/new-api:latest

Nginx 配置与 OneAPI 完全一致，流式响应同样需要 proxy_buffering off。

生产环境如果日活调用量比较大，光靠这行 docker run 起一个单机 MySQL 容器扛不了多久，两件事要提前想清楚：一是 SQL_DSN 连接串的参数要配完整（比如时间字段解析相关的参数），不同版本对时间格式的要求不完全一样，漏了容易在写调用日志时报时间解析错误；二是渠道调用日志表默认没有自动清理策略，跑上几个月这张表会膨胀到几百万行甚至更多，查询变慢，全站响应跟着一起变慢。建议自己写个定时任务按周期归档或删除超过一定期限的日志，不要指望官方版本自带这个能力。

重要配置差异（相比 OneAPI）

渠道配置

NewAPI 的渠道配置界面增加了以下字段：

测试模型：渠道自动测试时使用的模型（建议选低成本模型）
权重：同优先级渠道间的流量权重（与 OneAPI 一致）
标签：用于渠道分组管理（NewAPI 新增）

令牌（Token）配置

名称：customer-xxx
分组：会员用户（对应差异化定价）
额度：500,000
有效期：2027-06-01
模型限制：（可选）

注意：NewAPI 中”额度”的单位随配置的倍率而变，务必在用户文档中说明清楚额度换算关系。

这句话说白了就是：额度这个数字本身没有绝对含义，它只在”当前倍率体系”下才能换算成钱。如果你后续调整了某个模型的倍率，历史开出去的令牌额度并不会跟着重新换算——已经充值的额度数值不变，但同样的数值在新倍率下能兑换的对话量变了。这对做对外分发的团队是个隐性风险：你今天告诉客户”这些额度大概能用多少次 gpt-4o 对话”，明天把倍率从 1.5 调到 2.0，客户手里的额度实际购买力缩水了,容易引发投诉。稳妥的做法是倍率一旦对外公布就尽量少动；真要调价，走”新令牌用新倍率、老令牌到期后不续”的方式，而不是直接改全局倍率去影响存量用户。

系统设置关键项

设置项	说明
允许用户注册	是否开放自注册（内部用途建议关闭）
默认用户组	新注册用户自动归入的组
Midjourney 代理	Midjourney 代理服务地址（需自行准备）
邮件 SMTP	注册验证码/告警通知邮件配置

升级与 OneAPI 迁移

从 OneAPI 迁移到 NewAPI：两者数据库结构相似但不完全相同。建议：

先在测试环境部署 NewAPI，手动重新配置渠道和令牌
不要直接迁移 OneAPI 的数据库（结构差异可能导致问题）
旧令牌重新生成后通知用户更新

迁移时最常见的报错是直接拿 OneAPI 的 MySQL 数据导入 NewAPI 后，服务启动时报字段不存在或者类型冲突一类的错误——根因就是两边虽然从同一个上游分叉出来，字段增删和类型定义早就分道扬镳了：NewAPI 新增的用户组、按次计费相关表，OneAPI 库里根本不存在，反过来也一样。与其花时间对着两边的建表语句手动改字段，不如干脆走”新库 + 手动重建配置”的路子——渠道信息、模型倍率表这些配置项数量有限，人工在 NewAPI 后台重新填一遍，比处理一个字段错位、索引冲突的历史数据库省事得多。我见过团队硬着头皮改字段，最后还是因为索引冲突半途放弃、回到手动重建这条路。

NewAPI 自身升级：

docker pull calciumion/new-api:latest
docker stop new-api && docker rm new-api
# 重新执行 docker run（数据在 /data/new-api 中持久化）

什么时候该用 NewAPI，而不是继续用 OneAPI

功能表看着 NewAPI 全面碾压，但实际选型不能只看功能多少，还要看你的运维能力和业务形态是否匹配：

你的情况	建议
纯内部使用，不对外收费，团队规模小	OneAPI 就够，社区更大、issue 修复更快，没必要为了用不上的计费功能折腾迁移
要对外卖 API 额度或做转售	NewAPI 的用户组倍率、按次计费是刚需，OneAPI 做不到这种差异化定价
需要绘图/生成类任务（Midjourney、Suno 等）	NewAPI 原生支持任务队列管理，OneAPI 得自己额外接一层代理
团队没有专职运维、想要有人兜底出问题	两者都是开源自维护项目，没有商业支持，出了故障只能自己排查或等社区响应，这种情况更适合用有人托管运维的商业聚合网关

一句话总结：选 NewAPI 之前先问自己”我是不是真的需要对外差异化计费和绘图任务管理”，如果答案是否定的，迁移带来的维护成本（数据库结构、升级节奏都要重新适应）未必划算。

常见问题

渠道测试一切正常，但用户实际调用总是随机出现 429，怎么排查？ 这种情况大概率不是 NewAPI 本身的问题，而是”权重分流”和”上游真实并发限制”之间的错位。NewAPI 按权重把流量分给多个渠道，但它并不知道你配置的某个渠道背后的 API Key 在上游那边有多少并发上限——即便渠道测试（单次调用）显示健康，真实高并发场景下，如果大部分权重压给了一个并发上限很低的渠道，照样会被上游限流打回 429。排查思路：先看后台的调用日志，429 是不是集中在某一个渠道 ID 上；如果是，把这个渠道的权重调低，或者去上游把这个 Key 的并发额度提上去，而不是先怀疑 NewAPI 的调度逻辑有问题。

NewAPI 和 OneAPI 哪个更适合做对外商业分发？ NewAPI 的用户组差异化定价、按次计费、Midjourney 支持更适合对外商业分发场景；OneAPI 更适合内部工具或对稳定性要求高的自用场景（社区更大、issue 响应更快）。两者都是开源项目，无商业支持，需自行维护。

NewAPI 的内置聊天页面可以对外开放吗？ 可以，但功能较基础。如需完整的聊天产品体验，建议用第三方前端（如 ChatNextWeb、LibreChat）对接 NewAPI 后端，灵活性更高。

新版 API 格式（如 OpenAI Responses API）支持吗？ 取决于 NewAPI 版本和社区更新进度。建议在 GitHub 仓库确认最新支持情况，开源项目的新接口支持往往有一定滞后。