Skip to content

同一个 API,为什么各个工具的 Base URL 写法都不一样? ​

因为每个工具拼接请求地址的规则不同:有的只在你填的地址后面补 /chat/completions,有的会先补 /v1,还有的要求你直接填完整地址。搞清楚工具属于哪一类,就知道该填根地址、带 /v1 的地址,还是完整地址,绝大多数 404 也就消失了。

一个请求地址由三段组成 ​

以 OpenAI 兼容接口为例:

text
https://api.example.com   /v1        /chat/completions
└──── 主机(根地址)────┘ └版本┘ └──── 接口路径 ────┘

工具最终发出的地址 = 你填的内容 + 工具自动补上的部分。只要两部分拼起来刚好是上面这一整串,就能请求成功;少一段或多一段都会 404。

三类拼接规则 ​

第一类:只补接口路径(填到 /v1) ​

OpenAI 官方 SDK 就是这样:base_url 后面只拼 /chat/completions 或 /responses,所以 base_url 要带 /v1。大量基于 OpenAI SDK 的工具沿用了这个规则,例如 Cursor、Cline、Continue、LobeChat、Dify、n8n、Aider、Open WebUI。

第二类:补版本和路径(填根地址) ​

Anthropic 官方 SDK 会拼接 /v1/messages,所以 Claude Code、Anthropic SDK 的 Base URL 不能带 /v1。部分对话客户端也会自己补 /v1,例如 Cherry Studio、ChatBox、NextChat,填根地址即可。Google 的 Gemini SDK 同理,会自己拼 /v1beta。

第三类:要求完整地址 ​

有些工具把你填的内容当作最终地址,不做任何拼接,例如沉浸式翻译推荐填 .../v1/chat/completions。VS Code 的 Custom Endpoint 两种都支持,但官方建议直接填完整地址以免歧义。

常见工具对照 ​

工具规则示例写法
OpenAI SDK、Cursor、Cline、LobeChat、Dify、Aider只补路径https://api.example.com/v1
Anthropic SDK、Claude Code补 /v1/messageshttps://api.example.com
Gemini SDK、Gemini CLI补 /v1beta/...https://api.example.com
Cherry Studio、ChatBox、NextChat补 /v1/...https://api.example.com
沉浸式翻译完整地址最稳https://api.example.com/v1/chat/completions
VS Code Custom Endpoint有路径就原样用,否则补建议填完整地址

各工具的规则可能随版本变化,以工具自己的文档为准。

遇到 404 怎么排查 ​

  1. 看工具的请求日志或报错里的完整 URL。很多工具会打印实际请求的地址,一眼就能看出多了还是少了 /v1。
  2. 数一数 /v1 出现了几次:/v1/v1/ 说明你填了 /v1,工具又补了一次;完全没有 /v1 说明工具没补,你也没填。
  3. 用 curl 直接请求完整地址,确认服务本身没问题,再回头调工具配置。
  4. 确认协议对得上:给 Anthropic 协议的工具填了 OpenAI 兼容的地址(或反过来),也会 404 或 400。

小结 ​

记住一句话:OpenAI 系填到 /v1,Anthropic 和 Gemini 系填根地址,要求完整地址的就填到底。NiceAI 的具体写法见 接口地址要不要加 /v1。

延伸阅读 ​

NiceAI · 稳定的 AI 大模型 API 中转站