网关排障 · 渠道配置

New-API 接入 Gemini 模型列表获取失败深度排查指南

在开源网关 New-API / One-API 中接入 Gemini 渠道时点击“获取模型列表”报错,核心根因是 /v1beta 原生路由与 /v1 兼容路由拼装混淆,或 Cloudflare WAF 拦截了后端的探测请求。排障核心是使用底层探针区分网络层与路由层。

更新日期:2026-09-16·作者:词元AI中转站 技术团队·主词:New-API Gemini 模型列表失败
典型现象拉取超时 / 404 Not Found / JSON 报错
根本诱因路由类型错配 / Cloudflare 人机验证盾
工程建议手动指定模型代号 + OpenAI 兼容通道

1. New-API 模型拉取背后的底层通信机制

作为目前主流的开源大模型聚合分发系统,New-API(及上游 One-API)在管理员配置“渠道(Channel)”时提供了一个快捷功能——**获取模型列表**。该功能的后端实现逻辑极为明确:

  • New-API 服务端进程直接作为 HTTP 客户端,向管理员填写的 Base URL 发起同步 GET 请求。
  • 预期接收合法的 JSON 报文,将其中的模型列表数组解析后回填至前端输入框。

如果这一步报错,说明**从你的 New-API 部署服务器到上游服务节点之间的网络链路或协议握手存在根本性断裂**。

2. 两类协议拼装冲突:/v1 与 /v1beta 的灾难

最容易导致 404 或解析失败的误区,是对 New-API 内部的“渠道类型(Type)”逻辑理解不清:

New-API 渠道类型 拉取模型实际拼装的 URL 认证 Header 规范 正确的 Base URL 填写示范
Google Gemini 原生 {Base_URL}/v1beta/models?key={KEY} URL Query 或 x-goog-api-key https://generativelanguage.googleapis.com(末尾绝不能带 /v1
OpenAI 兼容渠道 {Base_URL}/v1/models Authorization: Bearer {KEY} https://api.gpt345.comhttps://api.gpt345.com/v1(系统自动去重)

很多开发者在使用第三方聚合中转站时,明明中转站提供的是标准 OpenAI 格式,却在 New-API 下拉框中误选了“Gemini”,且把 Base URL 填成了 https://api.gpt345.com/v1。New-API 最终拼出的地址成了 https://api.gpt345.com/v1/v1beta/models,服务端必然返回 404!

3. Cloudflare WAF / 5秒盾拦截的隐蔽表征

排查中第二大高频杀手是安全防御规则。当上游节点启用了 Cloudflare CDN 防护时:

  • New-API 后端底层由 Go 编写,默认的 HTTP 客户端请求头为 User-Agent: Go-http-client/1.1
  • Cloudflare 的 Bot Management 规则对于未携带合规浏览器指纹的请求极为敏感,常会直接下发 HTTP 403 并在响应体中返回 HTML 格式的**Managed Challenge(人机验证 5 秒盾)**。
  • New-API 拿到一堆 HTML 网页,强行执行 json.Unmarshal,就会在日志中打印经典的:invalid character '<' looking for beginning of value

4. 诊断探针:双协议端点连通性实测脚本

在 New-API 所在的服务器终端上,直接运行以下 Python 探针脚本,可以脱离 Web 界面,看清究竟是哪个环节被阻断:

newapi_gemini_probe.py(诊断模型列表探测链路)
import requests
import sys

def probe_model_list(base_url, api_key):
    print(f"[探针] 正在对 Base URL: {base_url} 进行双协议探测...")
    
    # 探针 1:测试标准 OpenAI 兼容模型列表
    openai_url = f"{base_url.rstrip('/')}/v1/models" if not base_url.endswith('/v1') else f"{base_url.rstrip('/')}/models"
    headers = {"Authorization": f"Bearer {api_key}"}
    print(f"\n[测试 1] 探测 OpenAI 规范路径: {openai_url}")
    try:
        r1 = requests.get(openai_url, headers=headers, timeout=10)
        print(f"HTTP 状态码: {r1.status_code}")
        if r1.status_code == 200:
            print("[成功] OpenAI 兼容模型列表获取正常!可在 New-API 中选用 'OpenAI' 类型渠道。")
        elif "cloudflare" in r1.text.lower() or "just a moment" in r1.text.lower():
            print("[拦截] 遭遇 Cloudflare WAF 人机验证拦截!")
        else:
            print(f"[响应片段]: {r1.text[:200]}")
    except Exception as e:
        print(f"[网络失败]: {e}")

    # 探针 2:测试 Gemini 原生模型列表
    gemini_url = f"{base_url.rstrip('/')}/v1beta/models?key={api_key}"
    print(f"\n[测试 2] 探测 Gemini 原生路径: {gemini_url}")
    try:
        r2 = requests.get(gemini_url, timeout=10)
        print(f"HTTP 状态码: {r2.status_code}")
        if r2.status_code == 200:
            print("[成功] Gemini 原生模型列表获取正常!可在 New-API 中选用 'Gemini' 类型渠道。")
        else:
            print(f"[响应片段]: {r2.text[:200]}")
    except Exception as e:
        print(f"[网络失败]: {e}")

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("用法: python newapi_gemini_probe.py  ")
    else:
        probe_model_list(sys.argv[1], sys.argv[2])

5. 生产化解法:手动配置模型与词元中转对接

在企业级网关运维中,过度依赖 UI 端的“自动拉取模型”本身就是一种脆弱的运维习惯。最优雅可靠的接入规范如下:

  1. 渠道类型统一选为“OpenAI 兼容”:规避 Google 原生接口的多重 URL 变体。
  2. Base URL 规范填写:填入 https://api.gpt345.com(词元中转网关)。
  3. 手动输入模型映射:直接在“模型”输入框中输入业务所需的精确代号,如 gemini-3-8-flashgemini-1.5-proclaude-opus-5
  4. 测试实际对话能力:点击“测试”按钮直接发送最小 Prompt,验证能否收到 200 响应。只要对话畅通,模型列表是否能拉取完全不影响线上生产。

6. 常见问题与排错手册

?为什么在 New-API 点击“获取模型列表”时会报 JSON 解析错误?

最常见的原因是请求触发了上游中转站或 Cloudflare 的安全防护(如 Managed Challenge 人机验证盾),上游返回的是 HTML 拦截页面而非 JSON 数据。Go 语言的 JSON 解码器试图将 HTML 字符串反序列化为数组结构时就会崩溃并抛出解析异常。

?New-API 渠道类型选择 Gemini 与选择 OpenAI 有何区别?

选择 Gemini 类型时,系统会尝试向 /v1beta/models 发起带 ?key= 的原生 Google 格式请求;而选择 OpenAI 类型时,系统会向 /v1/models 发起带 Authorization: Bearer 头的标准兼容请求。Base URL 必须与所选的渠道类型严格匹配。

?生产环境下是否必须依赖自动“获取模型列表”功能?

完全不需要。生产环境最佳实践是关闭自动拉取,在 New-API 渠道配置界面的“模型”输入框中手动填入业务所需的具体代号(如 gemini-3-8-flash、claude-opus-5),避免上游实验性废弃模型污染下发路由。

?如何通过词元中转网关快速配置 New-API?

在 New-API 中直接将渠道类型设为“OpenAI 兼容”,Base URL 填入 https://api.gpt345.com,填入词元 API Key 并在模型列表手动绑定 gemini-3-8-flash,即可瞬间跑通高可用调用。

* 本文由 词元AI中转站 技术团队根据大规模私有部署 New-API / One-API 网关集群运维经验原创整理。排查模型列表时请确保 API Key 已脱敏。最后修订:2026-09-16。

开源资料:New-API 开源项目仓库 · Google Gemini API Models 官方端点