New API 项目详细总结

新一代大模型网关与 AI 资产管理系统

一、项目概述

New API (GitHub: QuantumNous/new-api) 是一个面向合法授权场景的 AI API 网关与用量管理系统，为 AI 应用提供统一的基础设施。项目默认面向自用、团队内部和企业私有化部署。

• GitHub 星标: 43,000+ (截至 2026 年 7 月)
• Fork 数: 10,000+
• 开源协议: GNU AGPLv3
• 主要语言: TypeScript (前端) + Go (后端)
• 上游项目: One API (MIT 许可证)
• 官方网站: https://www.newapi.ai
• 官方文档: https://docs.newapi.pro/zh/docs
• Docker 镜像: calciumion/new-api:latest
• 最新版本: v1.0.0-rc.21 (2026-07-11)

New API 无缝集成全球主流 AI 服务提供商，包括 OpenAI、Anthropic、Google Gemini、DeepSeek、Midjourney、Suno 等 30+ 模型服务，支持将这些不同格式的 API 统一转换为 OpenAI 兼容、Claude 兼容或 Gemini 兼容格式。

二、核心特性

2.1 基础功能

2.2 授权用量与成本管理

• 支持合法授权场景下的内部充值与额度分配（易支付 EPay、Stripe）
• 组织内按次、按量或缓存命中成本核算
• 支持 OpenAI、Azure、DeepSeek、Claude、Qwen 等模型的缓存计费统计
• 面向内部管理或企业客户的灵活计费策略配置
• 模型定价设置支持分组感知的动态计算

2.3 授权与安全

• Discord 授权登录
• LinuxDO 授权登录
• Telegram 授权登录
• OIDC 统一认证
• Key 查询使用额度（配合 new-api-key-tool）
• Session 安全管理（活跃数限制、签发数限制、撤销保留等）

2.4 高级功能

API 格式支持

• OpenAI Responses API
• OpenAI Realtime API（含 Azure）
• Claude Messages 格式
• Google Gemini 格式
• Rerank 模型（Cohere、Jina）
• Midjourney-Proxy 接口
• Suno API 接口
• Dify ChatFlow 模式

智能路由

• 渠道加权随机分配
• 失败自动重试
• 用户级别模型限流
• 高级自定义路由能力

格式转换

Reasoning Effort 支持

通过模型名称后缀控制推理力度:

• OpenAI 系列: o3-mini-high / o3-mini-medium / o3-mini-low，gpt-5-high / gpt-5-medium / gpt-5-low
• Claude 思考模型: claude-3-7-sonnet-20250219-thinking
• Google Gemini 系列: gemini-2.5-flash-thinking / gemini-2.5-pro-thinking / gemini-2.5-pro-thinking-128，也可追加 -low / -medium / -high 控制思考力度

三、支持的模型与接口

3.1 模型类型

3.2 支持的接口列表

• 聊天接口 (Chat Completions)
• 响应接口 (Responses)
• 图像接口 (Image Generations)
• 音频接口 (Audio Transcription / Speech)
• 视频接口 (Video)
• 嵌入接口 (Embeddings)
• 重排序接口 (Rerank)
• 实时对话 (Realtime)
• Claude 聊天 (Messages)
• Google Gemini 聊天

四、部署指南

4.1 部署要求

4.2 方式一: Docker Compose（推荐）

# 克隆项目
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# 编辑配置
nano docker-compose.yml

# 启动服务
docker-compose up -d

4.3 方式二: Docker 命令

使用 SQLite（默认，最简单）:

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

使用 MySQL:

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

4.4 方式三: 宝塔面板

1. 安装宝塔面板（>= 9.2.0 版本）
2. 在应用商店搜索 "New-API"
3. 一键安装

4.5 方式四: 1Panel 面板

通过 1Panel 面板图形化界面快速部署，适合不熟悉命令行的用户。

4.6 部署后访问

部署完成后，访问 http://localhost:3000 即可使用。默认管理员账号: root / 123456（首次登录后请修改密码）。

五、核心环境变量配置

完整环境变量参考: https://docs.newapi.pro/zh/docs/installation/config-maintenance/environment-variables

六、使用指南

6.1 基本使用流程

1. 添加渠道: 在管理后台 -> 渠道管理中添加上游 AI 服务提供商的 API Key 和接口地址
2. 创建令牌: 在令牌管理中创建 API Token，设置可用模型和额度
3. 调用 API: 使用生成的 Token 作为 API Key，通过 New API 的统一入口调用

6.2 API 调用示例

New API 兼容 OpenAI API 格式，调用方式与 OpenAI 官方 API 一致:

curl https://your-newapi-domain/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-newapi-token" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello, world!"}
    ],
    "stream": true
  }'

6.3 智能路由配置

• 渠道加权: 在渠道编辑中设置权重，系统按权重随机分发请求
• 失败重试: 在 设置 -> 运营设置 -> 通用设置 中配置失败重试次数
• 模型限流: 在 设置 -> 速率限制设置 中配置总请求数限制和成功请求数限制

6.4 缓存计费

开启缓存计费后，在缓存命中时按设定比例计费: - 在 系统设置 -> 运营设置 中设置提示缓存倍率 - 在渠道中设置提示缓存倍率，范围 0-1（如 0.5 表示缓存命中时按 50% 计费） - 支持渠道: OpenAI、Azure、DeepSeek、Claude

6.5 Playground

内置 Playground 功能，支持直接在 UI 中测试模型调用，包括请求参数面板用于调整模型行为。

七、多机部署与集群

7.1 多节点注意事项

• 所有节点必须使用同一个主数据库，并设置相同的 SESSION_SECRET
• 连接同一个 Redis 的节点必须设置相同的 CRYPTO_SECRET
• 否则 Access Token、Refresh 会话和临时鉴权流程无法一致校验

7.2 Redis 拓扑对比

八、相关项目

上游项目

配套工具

友情链接

• CoAI
• GPT-Load
• LangBot
• Cherry Studio (合作伙伴)
• Aion UI (合作伙伴)

九、最新版本更新亮点 (v1.0.0-rc.21)

发布日期: 2026-07-11

新功能

• GPT-5.6 缓存写入计费支持，将 OpenAI cache_write_tokens 按缓存创建费率计费
• 定价页面支持分组感知的动态计算
• 模型定价设置新增"未设置价格模型"标签页
• Playground 新增请求参数面板，可直接在 UI 中调整模型行为
• 渠道列表支持手动调整列宽
• 日志新增流式时间指标和任务详情视图
• 增强文本协议转换和高级自定义路由能力

Bug 修复

• 修复浏览器翻译导致 React 页面渲染损坏
• 修复仅大小写不同的自定义模型名称添加问题
• 修复配额预消费和图像流断开边缘情况
• 修复 Codex 响应透传字段同步
• 修复并发更新下订阅重置可靠性

十、许可证与合规

许可证

• 采用 GNU AGPLv3 开源协议
• 可自由使用、修改和分发
• 核心义务: 如果修改并作为网络服务(SaaS)部署，必须在 AGPLv3 下提供完整源代码
• 商业授权: 如组织政策不允许 AGPLv3，可联系 [email protected]

合规要求

• 用户必须合法取得上游 API Key、账号、模型服务或接口权限
• 面向公众提供生成式 AI 服务时，应遵守《生成式人工智能服务管理暂行办法》等监管要求
• 需完成备案、许可、内容安全、实名、日志留存、税务和上游授权等合规义务

十一、技术架构总结

New API 的技术架构可以归纳为以下几层:

1. 网关层: 统一 API 入口，兼容 OpenAI 标准格式，处理请求路由、负载均衡、失败重试
2. 适配层: 格式转换引擎，支持 OpenAI/Claude/Gemini 格式互转
3. 管理层: 用户管理、令牌权限、模型访问控制、渠道管理
4. 计费层: 按次/按量计费、缓存命中成本核算、额度分配、企业账务管理
5. 数据层: 支持 SQLite/MySQL/PostgreSQL，Redis 缓存加速
6. 监控层: 实时数据看板、用量统计、成本分析、日志审计

后端使用 Go 语言开发，保证高并发性能；前端使用 TypeScript + React 构建现代化 UI。

十二、总结

New API 是目前 GitHub 上最流行的 AI API 网关项目之一（4.3 万星），它在 One API 的基础上进行了全面的二次开发，核心价值在于:

1. 统一入口: 将 30+ AI 服务提供商的 API 统一为一个入口，兼容 OpenAI 格式
2. 格式互转: 支持 OpenAI/Claude/Gemini 三大格式互转，消除 API 差异
3. 智能路由: 多渠道负载均衡、加权随机、失败自动重试，提升服务可用性
4. 成本管控: 精细化的计费体系，支持缓存计费、分组计费、企业账务管理
5. 安全管控: 令牌权限管理、模型访问控制、多种登录方式（Discord/Telegram/OIDC）
6. 易部署: Docker 一键部署，SQLite 开箱即用，同时支持 MySQL/PostgreSQL 和集群模式
7. 数据兼容: 完全兼容 One API 数据库，可无缝迁移

适合场景: 个人 AI 应用统一管理、团队内部 AI 资源共享、企业私有化 AI 网关部署。