====== NewAPI 与 Sub2API 对接指南 ======

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

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

===== 整体架构 =====

整条请求链路如下：

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

每个环节的职责：

  - **AI 订阅服务**：模型提供商提供的订阅访问权限，通过 OAuth 授权给 Sub2API
  - **Sub2API**：接收 OAuth 授权(([[zh:sub2api:initial_setup|Sub2API 初始配置]]))，将订阅额度转化为标准 OpenAI 兼容 API 接口
  - **NewAPI**：将 Sub2API 作为上游渠道接入，统一管理 API 密钥、用量配额和模型访问权限(([[zh:newapi:initial_setup|NewAPI 初始设置指南]]))
  - **下游客户端**：通过 NewAPI 的单一入口调用所有模型

===== 前提条件 =====

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

  - Sub2API 已部署并可访问(([[zh:sub2api:deploy|Sub2API Docker 部署指南]]))
  - Sub2API 中已配置 AI 订阅的 OAuth 渠道，处于活跃状态
  - NewAPI 已部署并可访问(([[zh:newapi:deploy|NewAPI Docker 部署指南]]))
  - Sub2API 已创建 API 密钥并分配了对应的 OAuth 渠道

===== 将 Sub2API 接入 NewAPI =====

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

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

**验证渠道连通性**：

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

<code bash>
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
  }'
</code>

如果 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 的托管规则拦截(([[zh:newapi:deploy|NewAPI Docker 部署指南]]))。可在 Cloudflare 面板中添加自定义规则：`User Agent contains OpenAI/Python` → **Skip** → 勾选 **All managed rules**。

**Sub2API 返回 401 Unauthorized**

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

{{tag>NewAPI Sub2API OAuth 对接 集成 API网关 配置}}