NewAPI 上游渠道接入完整教程

NewAPI 是目前最常用的模型 API 聚合面板。把 OpenAI 兼容网关配置成它的上游渠道后，面板里的所有下游 Key 就能统一调用 Claude、GPT、Gemini 等全部模型。整个过程约 5 分钟。

前置准备

一个可用的 API Key（在控制台创建，格式 sk-zerofa-...）
钱包余额大于 0（计费说明）
NewAPI 面板的管理员权限

第一步：添加渠道

进入 NewAPI 管理后台 → 渠道 → 添加渠道，按下表填写：

字段	填写值
类型	OpenAI
Base URL / 代理	`{{API_BASE_URL}}`（不带 `/v1` 后缀，NewAPI 会自动拼接）
密钥	你的 `sk-zerofa-...` Key
模型	从模型广场复制需要的模型名，或点“获取模型列表”自动拉取

第二步：验证渠道连通

保存后在渠道列表点“测试”，NewAPI 会发一条最小对话请求。也可以直接用 curl 验证上游本身：

bash

curl https://zerofa.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-zerofa-..." \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "ping"}]
  }'

第三步：模型映射与分组（可选）

模型重定向：下游用别名调用时，在渠道的“模型重定向”里把别名映射到真实模型名。
分组：给渠道设置分组后，只有同分组的下游令牌会路由到这个渠道，便于按业务隔离。
权重与优先级：多渠道场景用权重做流量分配、优先级做主备切换。

常见报错排查

现象	原因与处理
测试返回 401	密钥填错或已删除；确认 Key 完整复制、未过期，必要时在控制台重建。
404 model_not_found	渠道的模型列表里没有该模型名；模型名区分大小写，从模型广场原样复制。
Base URL 测试超时	URL 多写了 `/v1` 或结尾斜杠导致路径拼接错误；只填根地址。
429	见429 限流完全排查手册；也可在控制台给 Key 调高 RPM。

接入后

下游业务无需任何改动：NewAPI 令牌照常分发，新模型上线后在渠道模型列表里追加即可。全部模型与实时价格见模型广场，报错口径见错误码与计费规则。

第一步：添加渠道

进入 NewAPI 管理后台 → 渠道 → 添加渠道，按下表填写：

字段

填写值

类型

OpenAI

Base URL / 代理

{{API_BASE_URL}}（不带 /v1 后缀，NewAPI 会自动拼接）

密钥

你的 sk-zerofa-... Key

模型

从模型广场复制需要的模型名，或点“获取模型列表”自动拉取

第二步：验证渠道连通

保存后在渠道列表点“测试”，NewAPI 会发一条最小对话请求。也可以直接用 curl 验证上游本身：

bash

curl https://zerofa.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-zerofa-..." \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "ping"}]
  }'

第三步：模型映射与分组（可选）

模型重定向：下游用别名调用时，在渠道的“模型重定向”里把别名映射到真实模型名。

分组：给渠道设置分组后，只有同分组的下游令牌会路由到这个渠道，便于按业务隔离。

权重与优先级：多渠道场景用权重做流量分配、优先级做主备切换。

常见报错排查

现象

原因与处理

测试返回 401

密钥填错或已删除；确认 Key 完整复制、未过期，必要时在控制台重建。

404 model_not_found

渠道的模型列表里没有该模型名；模型名区分大小写，从模型广场原样复制。

Base URL 测试超时

URL 多写了 /v1 或结尾斜杠导致路径拼接错误；只填根地址。

429

见429 限流完全排查手册；也可在控制台给 Key 调高 RPM。