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

- - 开篇：为什么我们需要一个"大模型统一网关"？
  - 一、项目背景与发展历程
  - [二、核心特性详解（为什么 New API 比竞品强）](#二、核心特性详解（为什么 New API 比竞品强）)
  - - [1. 统一接口 + 多格式转换（最强兼容性）](#1. 统一接口 + 多格式转换（最强兼容性）)
    - [2. 智能路由与高可用](#2. 智能路由与高可用)
    - [3. 精细计费与支付闭环（个人/企业必备）](#3. 精细计费与支付闭环（个人/企业必备）)
    - [4. 现代化管理后台](#4. 现代化管理后台)
    - [5. 多语言 & 多租户](#5. 多语言 & 多租户)
    - [6. 扩展集成](#6. 扩展集成)
    - [7. 安全与可观测性](#7. 安全与可观测性)
  - [三、支持的模型与渠道（30+ 服务商，100+ 模型）](#三、支持的模型与渠道（30+ 服务商，100+ 模型）)
  - [四、部署安装完整教程（10 分钟上手）](#四、部署安装完整教程（10 分钟上手）)
  - - [推荐方式 1：Docker Compose（最简单，生产首选）](#推荐方式 1：Docker Compose（最简单，生产首选）)
    - [方式 2：单容器 Docker](#方式 2：单容器 Docker)
    - [方式 3：宝塔/1Panel 一键安装](#方式 3：宝塔/1Panel 一键安装)
    - [方式 4：手动编译（开发者）](#方式 4：手动编译（开发者）)
  - 五、环境变量完整配置表
  - 六、后台管理实操指南
  - 七、客户端使用示例（零代码改动接入）
  - 八、高级功能实战
  - 九、与竞品对比
  - 十、实际案例与最佳实践
  - [十一、常见问题 FAQ](#十一、常见问题 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、CSDN、知乎、B 站涌现大量部署教程。2026 年 2 月最新版 v0.10.9-alpha.6 修复了状态码映射、Token 搜索、Header 透传等问题，稳定性大幅提升。

许可证：AGPL-3.0（网络服务部署必须开源）。商业闭源授权请邮件 support@quantumnous.com。

免责声明：遵守各上游服务商条款（如 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（最简单，生产首选）

bash 复制代码

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

bash 复制代码

docker pull calciumion/new-api:latest

# SQLite
docker 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：手动编译（开发者）

bash 复制代码

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

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

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

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

完整列表见官方文档。

六、后台管理实操指南

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

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

Python OpenAI SDK（最简单）：

python 复制代码

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 分钟上手，终身受益。

立即行动：

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