New API

[!info] 知识库定位 这是一篇 工具评估 / 使用笔记，重点回答”它值不值得用、怎么用、什么时候不用”。 底层概念链接到 related_concepts；真实项目落地链接到 used_in_projects。

基于 One API 二次开发的新一代大模型网关与 AI 资产管理系统，将 OpenAI、Claude、Gemini、DeepSeek 等数十种大模型 API 统一封装为兼容格式，一个后台搞定渠道管理、用户配额和计费。

为什么需要它

手里攥着 OpenAI、Claude、Gemini、DeepSeek 多家 API Key，每家格式不同、计费不同，切换模型要改代码。企业场景还需要按团队分配额度、统计用量、控制成本。New API 把这些全部收归一个入口：统一格式、统一鉴权、统一计费，客户端只需改一个 base_url 就能切模型。对个人开发者来说，它解决了”Key 管理混乱 + 国内直连障碍 + 多模型切换摩擦”三大痛点。

核心优势

• 统一 API 格式：OpenAI / Claude / Gemini 三种格式互转，客户端无需改动即可切换后端模型提供商
• 渠道智能路由：加权随机负载均衡 + 失败自动重试/故障转移，多 Key 轮询降低单 Key 限流风险
• 完善的计费体系：按次/按量/按秒/按像素/阶梯计费，支持缓存 Token 计费统计，内置支付宝/微信/Stripe 在线充值
• 国产模型全覆盖：通义千问、文心一言、讯飞星火、智谱 ChatGLM、字节豆包、Kimi、百川等 20+ 渠道类型
• 数据看板：可视化统计面板，按模型/用户/时段分析用量和成本
• 兼容 One API：完全兼容原版 One API 数据库，可无缝迁移

性能表现

官方无公开 benchmark。作为 Go 编写的代理层，同地域部署延迟开销约 5-20ms。社区反馈在月调用千万级别下表现稳定。

快速上手

安装

# Docker 一键部署（SQLite 模式，最简方案）
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

# Docker Compose（推荐生产环境）
git clone https://github.com/QuantumNous/new-api.git
cd new-api
# 编辑 docker-compose.yml 配置数据库和 Redis
docker-compose up -d

# MySQL 模式
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:password@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

部署后访问 http://localhost:3000，默认账号 root，密码 123456（首次登录务必修改）。

最小示例

# 用标准 OpenAI SDK 调用，只需改 base_url 和 api_key
import openai

client = openai.OpenAI(
    api_key="sk-你的NewAPI令牌",
    base_url="http://你的地址:3000/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",        # 或 claude-3-5-sonnet、gemini-pro 等
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

配置要点

适用场景

适合：

• 企业/团队需要统一管理多种 AI 模型 API，按部门/项目分配配额
• 个人开发者手里有多家 API Key，想要一个入口统一调用
• 需要国内可用的 AI API 中转，解决直连 OpenAI/Claude 的网络问题
• 想搭建小型 AI API 转售平台，需要计费和用户管理
• 团队使用 Cherry Studio、LobeChat、Cursor、Claude Code 等工具，需要统一后端入口
• 需要聚合国产模型（通义千问、文心一言、讯飞星火等）做统一接口管理

不适合：

• 只用一家 API 且无管理需求（直接调用更简单，少一层代理）
• 对延迟极度敏感的实时场景（代理层增加 5-20ms）
• 数据安全要求极高的场景且无法自建（中转模式下平台可见请求数据）
• 月均 API 消耗 < 500 元的小团队（商业聚合平台可能比自建更划算）

已知坑 & 注意事项

[!warning] 许可证为 AGPLv3 开源使用免费，但如需移除品牌/版权信息、OEM 集成闭源产品、规避开源义务，需联系作者购买商业许可（support@quantumnous.com）。

[!warning] 中转模式下数据隐私 平台作为中间代理，理论上可见所有请求和响应数据。敏感场景务必自建部署，不要使用第三方托管的 New API 实例。

[!warning] 多机部署必须配置密钥 集群部署时 SESSION_SECRET 和 CRYPTO_SECRET 必须手动设置，否则 session 和加密数据在不同节点间无法互通。两台机器的 SQL_DSN 应指向不同数据库。

• Gemini 格式转换限制：Gemini → OpenAI 兼容格式仅支持文本，暂不支持函数调用
• OpenAI Responses 转换：与 Chat Completions 的互转功能尚在开发中
• 默认密码：首次部署默认 root/123456，上线前必须修改
• Breaking Changes：项目迭代较快（497+ Releases），升级前务必查看 Release Notes，大版本可能有数据库 schema 变更

竞品对比

选择建议：个人用/小团队需要开箱即用的管理后台 → New API；纯 Python 技术栈想要轻量代理库 → LiteLLM；只需要基础转发不改原版 → One API；需要商业化运营 → 对比 New API 和 One Hub 的商业许可条款。

生态 & 社区

• 维护状态：活跃维护，497+ Releases，270+ 贡献者，36.5k+ Stars
• 文档质量：好 — 有官方文档站 https://doc.newapi.pro，README 详尽，部署指南覆盖多种场景
• 周边生态：兼容 Cherry Studio、LobeChat、Cursor、Claude Code、Open WebUI、NextChat、ChatBox、Dify、LangChain 等主流 AI 工具
• 社区活跃度：GitHub Issues 响应较快，中文社区活跃
• 部署方式：Docker / 宝塔面板 / 1Panel / 离线部署，覆盖面广

引入评估

结论：推荐 — 如果你有管理多种 AI 模型 API 的需求，New API 是目前中文社区最成熟、功能最全面的开源方案。开箱即用的计费系统、完善的渠道管理和数据看板使其在企业场景也够用。主要顾虑是 AGPLv3 许可证和较快的版本迭代节奏。

推荐引入版本：calciumion/new-api:latest（Docker 镜像），建议锁定到具体 release tag 避免自动升级引入 breaking changes。

相关链接

前置知识：OpenAI API · 大模型网关 · API 中继与格式转换 竞品：One API · LiteLLM · One Hub 使用场景：API 管理 · 负载均衡 · AI 工具链 底层概念：负载均衡 · API 中继与格式转换

• GitHub 仓库
• 官方文档
• Docker Hub

个人备注

{留白，供后续补充实际使用心得}