跳到主要内容

Base URL 与 /v1 路径问题

Base URL 填错时，请求通常会返回 404，或被发送到错误的协议端点。最容易混淆的地方是：有些 SDK 会自动追加 /v1 和接口路径，有些客户端只追加 /chat/completions，而原始 HTTP 请求必须填写完整地址。

先理解三种地址​

地址类型示例适用场景
站点根地址https://www.bita-api.comAnthropic SDK、Google Gen AI SDK、Claude Code、Cherry Studio 等会自行追加版本路径的客户端
版本化 Base URLhttps://www.bita-api.com/v1OpenAI SDK、Codex Responses 等会在 Base URL 后追加接口路径的客户端
完整接口地址https://www.bita-api.com/v1/chat/completionscURL、Postman、requests、fetch 等直接发送 HTTP 请求的场景

可以把最终地址理解为：

最终请求地址 = 客户端中的 Base URL + 客户端自动追加的路径

例如，OpenAI SDK 使用 https://www.bita-api.com/v1，再追加 /chat/completions；Anthropic SDK 使用 https://www.bita-api.com，再追加 /v1/messages。

“API 地址”这个名称不能判断是否需要 /v1

不同工具可能把同一个输入框命名为 Base URL、API URL、Endpoint 或 API 地址，但它们自动追加路径的规则并不相同。应以对应工具的接入文档为准。

常用地址速查​

SDK 和第三方工具​

客户端应填写的 Base URL客户端追加的常用路径
OpenAI Python / Node.js SDKhttps://www.bita-api.com/v1/models、/chat/completions、/responses
Anthropic SDKhttps://www.bita-api.com/v1/models、/v1/messages
Google Gen AI SDKhttps://www.bita-api.com/v1beta/models/...
Claude Codehttps://www.bita-api.com/v1/messages
Cherry Studio 的 OpenAI 服务商https://www.bita-api.com/v1/models、/v1/chat/completions
CC Switch 中的 Codex Responseshttps://www.bita-api.com/v1/responses
CC Switch 中的 Claude Codehttps://www.bita-api.com/v1/messages

原始 HTTP 请求​

接口完整地址
OpenAI 模型列表https://www.bita-api.com/v1/models
OpenAI Chat Completionshttps://www.bita-api.com/v1/chat/completions
OpenAI Responseshttps://www.bita-api.com/v1/responses
Anthropic Messageshttps://www.bita-api.com/v1/messages
Gemini 模型列表https://www.bita-api.com/v1beta/models
Gemini 生成内容https://www.bita-api.com/v1beta/models/MODEL_ID:generateContent

原始请求的请求方法也必须正确：模型列表使用 GET，生成接口通常使用 POST。

为什么会出现 /v1/v1？​

客户端已经自动追加 /v1/...，但 Base URL 中又包含了 /v1，就会形成重复路径。例如：

错误 Base URL: https://www.bita-api.com/v1
客户端追加:    /v1/messages
最终地址:      https://www.bita-api.com/v1/v1/messages

这在 Anthropic SDK、Claude Code、Google Gen AI SDK 和 Cherry Studio 中比较常见。对应修正如下：

错误地址正确地址
Claude Code：https://www.bita-api.com/v1https://www.bita-api.com
Anthropic SDK：https://www.bita-api.com/v1https://www.bita-api.com
Google Gen AI SDK：https://www.bita-api.com/v1betahttps://www.bita-api.com
Cherry Studio：https://www.bita-api.com/v1https://www.bita-api.com

不要通过把完整接口地址填入 Base URL 来修复。例如 Anthropic SDK 的 Base URL 不应填写 /v1/messages，否则 SDK 仍会继续追加自己的路径。

为什么会遗漏 /v1？​

另一类客户端只在 Base URL 后追加 /models、/chat/completions 或 /responses。如果 Base URL 只写根地址，最终路径就会缺少 /v1：

错误 Base URL: https://www.bita-api.com
客户端追加:    /chat/completions
最终地址:      https://www.bita-api.com/chat/completions

OpenAI Python 和 Node.js SDK 应填写：

https://www.bita-api.com/v1

Codex 直接使用 Bita API 的 Responses 接口时也应使用包含 /v1 的 Base URL。通过其他本地代理或协议转换工具接入时，应以代理实际要求为准。

/v1 和 /v1beta 可以互换吗？​

不可以。它们代表不同的兼容协议路径：

  • /v1/chat/completions 和 /v1/responses 属于 OpenAI 兼容接口。
  • /v1/messages 属于 Anthropic Messages 兼容接口。
  • /v1beta/models/...:generateContent 属于 Gemini 原生接口。

即使目标模型名称相同，也不能把一种协议的请求体直接发送到另一种协议路径。选择接口时应同时确认：

  1. 当前 SDK 或工具使用哪一种协议。
  2. 目标模型是否支持该端点类型。
  3. 请求体字段是否符合该协议。

为什么打开根地址正常，API 请求却失败？​

浏览器访问 https://www.bita-api.com 只能证明站点根地址可以连接。API 调用还需要正确的接口路径、请求方法、鉴权请求头和请求体。

可以先测试模型列表：

curl -i "https://www.bita-api.com/v1/models" \
  -H "Authorization: Bearer $BITA_API_KEY"

如果返回 200，说明域名、OpenAI 路径和密钥基本正确，再继续测试实际生成接口。如果返回的是 HTML 页面而不是 JSON 错误，通常说明请求落到了网站页面或错误的代理路径。

为什么模型列表成功，生成请求仍返回 404？​

模型列表成功说明基础地址和鉴权大概率正确，但不能证明生成端点匹配。继续检查：

  • 模型 ID 是否与列表返回值完全一致。
  • 模型是否属于密钥当前分组。
  • 模型端点类型是 Chat、Responses、Anthropic Messages 还是 Gemini。
  • 客户端是否把 /chat/completions、/responses 或 /messages 追加到了预期地址。
  • Gemini 路径中的模型 ID 是否被重复写成 models/models/...。

具体参见查询可用模型和模型不可用。

如何确认客户端实际请求了哪个地址？​

按下面的顺序定位：

  1. 查看客户端状态页、错误消息或调试日志中的请求 URL。
  2. 检查控制台使用日志中的接口和模型信息。
  3. 用相同密钥发送本页的最小 cURL 请求，与客户端结果比较。
  4. 检查环境变量、项目配置和全局配置是否存在多个 Base URL。
  5. 修改配置后完全重启客户端、编辑器、终端进程或容器。
分享调试日志前先检查

详细 HTTP 日志可能包含 Authorization、x-api-key、x-goog-api-key、查询参数中的密钥或业务请求内容。发送日志前必须脱敏。

常见现象​

现象优先检查
404 Not FoundBase URL 是否重复或遗漏版本路径，接口路径是否拼错
请求地址含 /v1/v1/messagesAnthropic 或 Claude Code Base URL 应改为站点根地址
请求地址含 /v1beta/v1betaGemini SDK Base URL 应改为站点根地址
请求地址缺少 /v1OpenAI SDK Base URL 应包含 /v1
返回 HTML 而不是 JSON请求可能落到网站页面、错误反向代理或登录页
405 Method Not Allowed完整路径可能存在，但 GET、POST 等请求方法错误
401 Unauthorized地址可能已经到达 API；继续检查密钥和鉴权请求头
模型列表成功、对话失败模型 ID、模型分组或生成端点不匹配
修改后仍请求旧地址运行中的进程未重启，或配置被环境变量、全局设置覆盖

地址填写建议​

  • 始终使用 HTTPS 和域名 www.bita-api.com，不要改用解析出的 IP 地址。
  • Base URL 末尾通常不需要 /，避免部分客户端拼出双斜杠。
  • 不要把 API 密钥放入 Base URL。
  • 不要在 Base URL 后填写模型 ID、请求参数或 chat/completions 等具体资源，除非工具明确要求完整接口地址。
  • 为不同协议创建独立的客户端配置，不要让 OpenAI、Anthropic 和 Gemini 共用一个模糊的“自定义地址”。

仍无法定位时，请提供脱敏后的 Base URL、客户端名称和版本、实际请求路径、HTTP 状态码及错误消息。鉴权错误参见 API Key 与鉴权问题，其他状态码参见常见错误码。