NewAPI 与 Sub2API 对接指南

NewAPI 是一款开源 AI API 网关，负责多密钥管理、负载均衡和下游分发。Sub2API 是一款 AI API 中转平台，能将 AI 订阅服务的额度通过 OAuth 转化为标准 OpenAI 兼容 API 接口。

本文介绍如何将 Sub2API 作为 NewAPI 的上游渠道接入，使下游客户端通过 NewAPI 一条链路调用 AI 模型。

整条请求链路如下：

AI 订阅服务 → Sub2API（OAuth 中转） → NewAPI（API 网关） → 下游客户端

每个环节的职责：

1. AI 订阅服务：模型提供商提供的订阅访问权限，通过 OAuth 授权给 Sub2API
2. Sub2API：接收 OAuth 授权¹⁾，将订阅额度转化为标准 OpenAI 兼容 API 接口
3. NewAPI：将 Sub2API 作为上游渠道接入，统一管理 API 密钥、用量配额和模型访问权限²⁾
4. 下游客户端：通过 NewAPI 的单一入口调用所有模型

开始对接前，需要确保以下服务已就绪：

1. Sub2API 已部署并可访问³⁾
2. Sub2API 中已配置 AI 订阅的 OAuth 渠道，处于活跃状态
3. NewAPI 已部署并可访问⁴⁾
4. Sub2API 已创建 API 密钥并分配了对应的 OAuth 渠道

在 NewAPI 管理后台添加上游渠道：

• 登录 NewAPI 管理后台
• 进入渠道 → 添加渠道
• 类型：选择自定义渠道（Custom）
• 名称：填写可识别的名称，如「Sub2API-上游」
• Base URL：填写 Sub2API 的完整地址，末尾加 `/v1`
  1. 如果两台服务在同一台服务器：`http://127.0.0.1:8081/v1`
  2. 如果是不同服务器：`https://sub2api.your-domain.com/v1`
• 密钥：填入 Sub2API 管理后台生成的 API 密钥
• 模型映射：在模型配置中手动添加该 OAuth 渠道实际暴露的模型名称，可在 Sub2API 渠道详情页面查看
• 点击保存

验证渠道连通性：

添加完成后，在 NewAPI 渠道列表中确认新渠道状态为可用。然后通过 curl 测试：

curl https://your-newapi-domain.com/v1/chat/completions \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "模型名称",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 20
  }'

如果 OAuth 授权正常，应返回正常的 AI 响应。

除了 Sub2API 的 OAuth 渠道，NewAPI 还可以同时接入其他 AI 提供商，实现统一管理和模型切换。轻量文本决策类任务分配给 OAuth 渠道的模型，重量级或视觉类任务分配给通过 API Key 直连的提供商。在 NewAPI 中为每个渠道设置独立的模型映射即可。

NewAPI 返回 404 或「模型不存在」

Sub2API 暴露的模型名称需要与 NewAPI 渠道配置中的模型映射名称一致。在 Sub2API 渠道详情页面查看实际返回的模型名称，然后在 NewAPI 渠道配置中添加相同的名称。

请求被 Cloudflare WAF 拦截（HTTP 403）

下游 SDK（如 OpenAI Python 库）默认使用 `User-Agent: OpenAI/Python`，会被 Cloudflare WAF 的托管规则拦截⁵⁾。可在 Cloudflare 面板中添加自定义规则：`User Agent contains OpenAI/Python` → Skip → 勾选 All managed rules。

Sub2API 返回 401 Unauthorized

确认 Sub2API 的 API 密钥未过期、未被撤销，且已分配了 OAuth 渠道的访问权限。