AI API Base URL 末尾要不要加 v1？路径拼接与 404 排查指南

更新于 2026-11-04 · orcarouter.cyou

简答：绝大多数 OpenAI 兼容的 API 服务、SDK（如 openai-python）以及开发工具（如 Cursor），其 Base URL 末尾<strong>必须加上 <code>/v1</code></strong>。因为官方规范和主流中转网关通常将 <code>/v1</code> 作为根路径版本前缀，若漏掉会导致客户端请求拼接成错误的路径从而引发 <code>404 Not Found</code> 错误。极少数服务若在后台已内置版本路由，则无需重复填写。

定义：AI API Base URL 是客户端在请求大模型服务时拼接具体接口路径（如 <code>/chat/completions</code>）的基础根地址。

适用范围与核心结论

在对接 OpenAI 官方端点、各类第三方中转服务或使用 Cursor、Cherry Studio 等开发工具时，配置 Base URL 是最常见的起步环节。如果路径少写或多写了一个字符，往往会直接导致请求失败。

核心结论速查：

• 必须加 /v1 的场景： 使用 OpenAI 官方 Python/Node SDK、在 Cursor 的 Override OpenAI Base URL 中填入中转地址、绝大多数兼容 OpenAI 规范的第三方 API 网关。
• 不需要加 /v1 的场景： 部分自建本地推理后端（如部分 vLLM、Ollama 默认根路径或特定服务商已在服务端自动处理版本路由）。

为什么漏掉 /v1 会报 404 错误？

要理解为什么不能漏掉 /v1，需要明白 SDK 或客户端是如何组装最终请求地址的。以主流的 OpenAI Python SDK 为例：

from openai import OpenAI

client = OpenAI(
    base_url="https://api.example.com/v1",  # 规范的 Base URL 带 /v1
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}]
)

当调用 client.chat.completions.create() 时，SDK 会自动在 base_url 后面拼接具体的资源端点路径 /chat/completions：

• 正确拼接结果： https://api.example.com/v1 + /chat/completions = https://api.example.com/v1/chat/completions（服务器成功响应）
• 错误拼接结果（未填 /v1）： 若 base_url 误写为 https://api.example.com，实际发出的请求地址会变成 https://api.example.com/chat/completions。由于服务端标准路由通常挂载在 /v1 之下，服务器无法识别该路径，从而抛出 404 Not Found 错误。

主流工具与 SDK 的 Base URL 配置对照表

下表梳理了常见开发工具与 SDK 在填写 Base URL 时的标准规范及常见陷阱：

末尾带斜杠（/v1/）与不带斜杠（/v1）的区别

除了“要不要加 v1”，另一个高频失误是斜杠（/）的处理。在 HTTP 协议和大多数 HTTP 客户端库（如 httpx、axios）中，Base URL 末尾带不带斜杠对路径拼接有微妙的影响：

• 推荐写法（不带尾随斜杠）： https://api.example.com/v1 —— SDK 或客户端在拼接 /chat/completions 时会自动补全斜杠，变成 https://api.example.com/v1/chat/completions。
• 危险写法（带尾随斜杠）： https://api.example.com/v1/ —— 部分底层库在处理字符串拼接时，若遇到双斜杠或解析不当，可能拼出 https://api.example.com/v1//chat/completions，部分严谨的后端网关会因路径不匹配返回 404 或重定向错误。

错误分流与 404 排查步骤

假如你在配置后遇到了接口不通或 404 报错，请按以下步骤依次核验：

1. 检查控制台完整请求 URL： 打开代码调试日志或抓包工具，查看客户端实际发出的完整 URL 是 .../v1/chat/completions 还是 .../chat/completions。
2. 核对服务商文档： 登录你所使用的 API 服务商后台，查看其提供的 OpenAI 兼容接入示例。若文档中写明 base_url="https://xxx/v1"，则本地配置必须严格保持一致。
3. 排除多余路径： 确保没有把具体的端点（如把 /chat/completions）直接写进 Base URL 中。Base URL 永远只应精确到网关的根路径或版本根目录。

安全边界与使用建议

在多模型切换或接入第三方兼容网关时，建议将 base_url 和 api_key 统一通过环境变量（如 OPENAI_BASE_URL 和 OPENAI_API_KEY）进行托管，避免硬编码在业务源码中。同时，妥善保管你的凭证，防止因配置错误或代码泄露造成安全风险。

主流工具与 SDK 的 Base URL 配置规范对照

常见问题

为什么有的时候不加 /v1 也能调通？

极少数本地部署的推理框架（如部分自定义包装的后端）或已经在服务端做了智能重定向的网关，会自动拦截并补全缺失的版本路径。但对于绝大多数标准 OpenAI 兼容服务和官方 SDK 而言，不加 /v1 会直接导致 404 错误。

Base URL 末尾不小心多加了一个斜杠（/v1/）会怎样？

虽然部分健壮的网关能够自动过滤多余的斜杠，但仍有部分严格遵循规范的后端或反向代理会把请求解析为双斜杠路径（如 /v1//chat/completions），从而引发 404 或 422 错误。建议保持末尾干净，不要带斜杠。

Cursor 提示 404 或无法连接自定义模型，该怎么检查 Base URL？

请先前往 Cursor 的 Settings → Models 检查 Override OpenAI Base URL 开关是否开启，并确认填写的地址末尾包含正确的 /v1 后缀，且没有包含多余的 API 方法名。

相关阅读

• OpenAI API 401/403/404 错误排查
• OpenAI API endpoint 和 base URL 的区别
• Codex 配置 API Key 与 Base URL 步骤

参考资料

1. vertexaisearch.cloud.google.com（vertexaisearch.cloud.google.com）
2. github.com
3. developers.openai.com