New API 详解：新一代开源大模型统一网关与 AI 资产管理系统（深度 6000 字指南）

New API 详解：新一代开源大模型统一网关与 AI 资产管理系统（深度 6000 字指南）

• 开篇：为什么我们需要一个“大模型统一网关”？
• 一、项目背景与发展历程
• 二、核心特性详解（为什么 New API 比竞品强）
  • 1. 统一接口 + 多格式转换（最强兼容性）
  • 2. 智能路由与高可用
  • 3. 精细计费与支付闭环（个人/企业必备）
  • 4. 现代化管理后台
  • 5. 多语言 & 多租户
  • 6. 扩展集成
  • 7. 安全与可观测性
• 三、支持的模型与渠道（30+ 服务商，100+ 模型）
• 四、部署安装完整教程（10 分钟上手）
  • 推荐方式 1：Docker Compose（最简单，生产首选）
  • 方式 2：单容器 Docker
  • 方式 3：宝塔/1Panel 一键安装
  • 方式 4：手动编译（开发者）
• 五、环境变量完整配置表
• 六、后台管理实操指南
• 七、客户端使用示例（零代码改动接入）
• 八、高级功能实战
• 九、与竞品对比
• 十、实际案例与最佳实践
• 十一、常见问题 FAQ
• 结语

New API 详解：新一代开源大模型统一网关与 AI 资产管理系统（深度 6000 字指南）

开篇：为什么我们需要一个“大模型统一网关”？

在 2025-2026 年的 AI 浪潮中，开发者们面临的最大痛点不再是“有没有好模型”，而是“怎么高效、低成本、安全地用好几十个模型”。

OpenAI 的 GPT-5 系列推理能力顶尖，但价格高昂且有速率限制；Anthropic 的 Claude 3.7 Sonnet 在长上下文和思考模式上无敌，却接口完全不同；Google Gemini 2.5 系列多模态强悍，价格亲民，但 API 格式又是另一套；国内的通义千问、DeepSeek、豆包、文心一言、混元……每个平台都有自己的 Base URL、鉴权方式、计费规则、限流策略。更别提 Midjourney 绘画、Suno 音乐生成、Rerank 重排序、Realtime 实时语音对话这些非标准接口。

手动为每个应用适配？维护几十份配置文件？每次新模型出来就要改代码？企业内部多用户、多部门、多预算怎么管控？个人公益站怎么实现充值、配额、计费闭环？

New API（https://github.com/QuantumNous/new-api）正是为解决这些痛点而生的“下一代 LLM 网关 + AI 资产管理系统”。

它不是简单的中转代理，而是统一入口 + 智能路由 + 格式转换 + 精细计费 + 多租户管理的完整平台。一把钥匙（一个 OpenAI 兼容的 API Key），调用全球 30+ 服务商、100+ 模型，还能自动把 Claude 请求转成 OpenAI 格式、Gemini 转 OpenAI、甚至支持 OpenAI Responses / Realtime / Claude Messages / Gemini 原生格式双向转换。

官网：https://www.newapi.ai
文档：https://docs.newapi.pro
Docker 镜像：calciumion/new-api:latest

一、项目背景与发展历程

2023 年，songquanpeng 推出 One API，开源界第一款真正意义上的“OpenAI 兼容大模型聚合中转”，迅速成为自建 ChatGPT/Claude 替代方案的标配。但到 2025 年初，One API 停止维护，社区急需接棒者。

QuantumNous 团队在 2025 年 3 月左右接手 fork，命名为 New API，进行了大规模重构：

• 前端重写为现代 React/Next.js 风格 UI（原版是老式 Bootstrap）
• 增加 Claude Messages ↔ OpenAI 双向转换、Gemini 双向转换（文本）
• 支持 OpenAI 新一代 Responses API、Realtime API（含 Azure）
• 加入思考模式（reasoning_effort）、思考转内容（thinking-to-content）
• 支付系统（EPay、Stripe）、缓存计费、模型倍率灵活配置
• OAuth（Discord、Telegram、LinuxDO、OIDC）
• 多语言国际化（i18n）
• Pyroscope 性能剖析、Redis 缓存、RWMap 高并发优化
• 集成 Midjourney-Proxy、Suno-API、Dify ChatFlow

2025 年 8 月后，New API 成为主流替代，Linux.do、ZEEKLOG、知乎、B 站涌现大量部署教程。2026 年 2 月最新版 v0.10.9-alpha.6 修复了状态码映射、Token 搜索、Header 透传等问题，稳定性大幅提升。

许可证：AGPL-3.0（网络服务部署必须开源）。商业闭源授权请邮件 [email protected]。

免责声明：遵守各上游服务商条款（如 OpenAI 使用政策、中国《生成式人工智能服务管理暂行办法》），项目按“AS IS”提供，无任何保证。

二、核心特性详解（为什么 New API 比竞品强）

1. 统一接口 + 多格式转换（最强兼容性）

支持以下接口：

• /v1/chat/completions（OpenAI 标准，100% 兼容 SDK）
• /v1/responses（OpenAI 新 Responses API，正在开发）
• /v1/messages（Claude 原生）
• /v1/gemini/...（Gemini 原生）
• /v1/images/generations、 /v1/audio/transcriptions、 /v1/audio/speech
• /v1/embeddings、 /v1/rerank（Cohere/Jina）
• /v1/realtime（实时对话，Azure 兼容）

格式转换亮点：

• OpenAI 请求 → Claude Messages / Gemini（文本）
• Claude / Gemini → OpenAI
• Thinking-to-Content：Claude/Gemini 思考过程自动转为 content 输出
• Reasoning Effort：gpt-5-high/medium/low、o3-mini-high、claude-3-7-sonnet-20250219-thinking、gemini-2.5-pro-thinking-128 等后缀直接生效

2. 智能路由与高可用

• 渠道加权随机：不同渠道设置权重，实现成本/速度最优
• 失败自动重试：最多重试 3 次，切换下一个渠道
• 用户级模型限流：防止单用户刷爆
• 渠道亲和性：相同用户请求尽量走同一渠道（减少冷启动）
• 负载均衡 + 多机部署：Redis + Session Secret 实现集群

3. 精细计费与支付闭环（个人/企业必备）

• 按量计费：Prompt + Completion Token 分别计费，支持缓存命中打折
• 模型倍率：全局/分组/渠道多层倍率（如 Claude 8 倍、DeepSeek 0.6 倍）
• 在线充值：EPay（微信/支付宝）、Stripe（国际卡）
• 用户分组 + 渠道分组：不同用户组看到不同模型池、不同价格
• 额度查询工具：配合 neko-api-key-tool 可查剩余额度

4. 现代化管理后台

• 数据看板：实时 Token 用量、成本、用户分布、渠道健康度图表
• 用户/令牌管理：过期时间、IP 白名单、模型白名单、额度
• 渠道管理：一键获取模型列表、批量导入密钥、模型重定向
• 模型广场：可视化管理所有可用模型
• 日志审计：完整请求/响应记录（可关闭）

5. 多语言 & 多租户

简/繁中、英、法、日无缝切换，适合国际团队或公益站。

6. 扩展集成

• Midjourney-Proxy（绘画）
• Suno-API（音乐生成）
• Dify ChatFlow
• 自定义渠道（任意 OpenAI 兼容地址）

7. 安全与可观测性

• OIDC/Discord/Telegram 登录
• Pyroscope 性能剖析
• 请求体大小限制（防 Zip Bomb）
• 流式超时可配置

三、支持的模型与渠道（30+ 服务商，100+ 模型）

New API 支持几乎所有主流渠道：

• OpenAI 官方：GPT-5 系列、o3-mini、GPT-4o、DALL·E 等
• Azure OpenAI：全系列 + Realtime
• Anthropic Claude：3.7 Sonnet Thinking、全系列
• Google Gemini：2.5 Flash/Pro Thinking 系列
• DeepSeek：V3、R1
• 阿里通义千问：Qwen-Max、VL、Embedding、Rerank
• 字节豆包、百度文心、腾讯混元、硅基流动、Mistral、Groq、Together、Fireworks 等
• 国内公益/低价渠道：各种中转号池（支持批量密钥轮询）
• 绘画：Midjourney（通过 midjourney-proxy）
• 音乐：Suno
• 向量/重排序：text-embedding-3、BAAI/bge、gte-rerank 等

渠道添加时选择对应类型（如“通义千问”“Claude”“自定义”），填 Base URL + Key + 模型列表即可。支持模型重定向（如上游 “qwen-plus” 映射到对外 “gpt-4o”）。

四、部署安装完整教程（10 分钟上手）

推荐方式 1：Docker Compose（最简单，生产首选）

git clone https://github.com/QuantumNous/new-api.git cd new-api # 编辑 docker-compose.yml（设置密码、端口、Redis 等）nano docker-compose.yml docker compose up -d 

默认 SQLite，数据在 ./data。生产建议改 MySQL/PostgreSQL + Redis。

方式 2：单容器 Docker

docker pull calciumion/new-api:latest # SQLitedocker run --name new-api -d --restart always \ -p 3000:3000 \ -e TZ=Asia/Shanghai \ -v /your/data/path:/data \ calciumion/new-api:latest # MySQL 示例docker run --name new-api -d --restart always \ -p 3000:3000 \ -e SQL_DSN="root:yourpass@tcp(127.0.0.1:3306)/newapi?charset=utf8mb4"\ -e TZ=Asia/Shanghai \ -v /your/data:/data \ calciumion/new-api:latest 

方式 3：宝塔/1Panel 一键安装

宝塔面板 ≥9.2.0 应用商店搜索 “New-API” 一键安装；1Panel 同理。

方式 4：手动编译（开发者）

git clone ... go build -o new-api main.go ./new-api 

首次启动访问 http://your-ip:3000，默认管理员 root / 123456（立即修改！）。

Nginx 反代推荐配置（支持长连接）：

proxy_read_timeout 300s; proxy_send_timeout 300s; client_max_body_size 32m; 

多机集群：所有实例设置相同 SESSION_SECRET + CRYPTO_SECRET + Redis，数据库共享。

五、环境变量完整配置表

关键变量（.env 或 docker-compose）：

• SESSION_SECRET、CRYPTO_SECRET：必填，随机长字符串
• SQL_DSN：数据库连接
• REDIS_CONN_STRING：redis://user:pass@host:6379/0
• STREAMING_TIMEOUT=300
• MAX_REQUEST_BODY_MB=32
• AZURE_DEFAULT_API_VERSION=2025-04-01-preview
• PYROSCOPE_URL：性能监控地址
• ERROR_LOG_ENABLED=true

完整列表见官方文档。

六、后台管理实操指南

1. 渠道管理：添加渠道 → 选择类型（OpenAI、Claude、Gemini、通义千问、自定义）→ 填 Key/BaseURL → “获取模型列表” → 勾选需要的 → 保存。支持批量导入密钥（逗号分隔或换行）。
2. 模型定价：设置 → 模型 → 为每个模型设置输入/输出价格（美元/百万 Token），支持缓存价格。
3. 用户与令牌：创建用户 → 生成 Token → 设置额度、过期时间、允许模型、IP 白名单。
4. 分组管理：用户组 + 渠道组 + 倍率（0.6x~8x 常见）。
5. 支付设置：启用 EPay/Stripe，配置商户密钥。
6. 看板：实时监控 Token 消耗、成本、错误率。

七、客户端使用示例（零代码改动接入）

Python OpenAI SDK（最简单）：

from openai import OpenAI client = OpenAI( base_url="https://your-newapi.com/v1", api_key="sk-你的NewAPI令牌") response = client.chat.completions.create( model="gpt-5-high",# 或 claude-3-7-sonnet-20250219-thinking messages=[{"role":"user","content":"写一首诗"}], stream=True)for chunk in response:print(chunk.choices[0].delta.content or"", end="")

调用 Claude 原生：用 /v1/messages + Claude Token

调用 Gemini：/v1/gemini/...

LangChain / LlamaIndex / Dify / Open WebUI：只需把 base_url 改成 New API 地址，即可无缝使用所有模型。

Midjourney：配置 Midjourney-Proxy 渠道后，用 /mj 相关接口。

Suno：同理。

八、高级功能实战

1. 智能路由优化：

• 低价渠道权重高（DeepSeek 0.6x）
• 高质量渠道权重中（Claude 3x）
• 失败重试 + 渠道亲和性 = 99.9% 可用性

2. 缓存计费：OpenAI/Azure/DeepSeek/Claude/Qwen 等支持 prompt caching，计费自动打折。

3. Realtime API：支持 OpenAI + Azure 实时语音，适合语音助手。

4. 模型广场与重定向：对外统一模型名（如 “gpt-4o” 映射多个上游）。

5. 公益站搭建：用户自助注册 + 充值 + 额度消耗，配合 Cloudflare Tunnel + Nginx + Fail2ban 防刷。

九、与竞品对比

• vs One API：New API = One API 2.0，UI 更好、功能更多、持续维护。
• vs LiteLLM：LiteLLM 更轻量（单文件），New API 是“带后台管理系统”的企业级方案，支持计费、多租户、UI。
• vs 商业中转：免费开源、可自控数据、不怕跑路、成本更低。

十、实际案例与最佳实践

个人开发者：一台 2 核 4G 服务器 + New API + Open WebUI = 私人 ChatGPT/Claude/Gemini 超级客户端。
企业内部：多部门分组、预算分配、审计日志，合规可控。
公益站：Linux.do 社区多位大佬已部署，日活上千，结合 Cloudflare 防护。
最佳实践：

• 先小额测试渠道
• 重要模型多渠道冗余
• 定期导出数据库
• 开启错误日志 + Pyroscope 监控
• 生产必开 Redis

十一、常见问题 FAQ

Q：One API 数据库能直接用吗？
A：完全兼容，直接替换即可。

Q：如何支持新模型？
A：自定义渠道或等待官方更新（社区 PR 很快）。

Q：Token 消耗不准？
A：检查模型定价和缓存配置。

Q：流式中断？
A：调大 STREAMING_TIMEOUT 和 Nginx timeout。

Q：AGPLv3 担心什么？
A：自用/内网无忧，SaaS 对外服务需开源或商业授权。

更多 FAQ 见官方文档。

结语

New API 不是一个简单的中转工具，而是AI 时代的操作系统级基础设施。它让“一个 API Key，走遍 AI 世界”成为现实，让个人开发者、企业、公益站都能以最低成本、最高效率掌控自己的 AI 资产。

无论你是刚接触 AI 的新人，还是搭建千人大模型平台的架构师，New API 都值得立即部署。10 分钟上手，终身受益。

立即行动：

1. 星标仓库：https://github.com/QuantumNous/new-api
2. Docker 一键部署
3. 添加第一个渠道，生成第一个 Token
4. 用 OpenAI SDK 跑通第一个请求