外观
同一个 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/messages | https://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 怎么排查
- 看工具的请求日志或报错里的完整 URL。很多工具会打印实际请求的地址,一眼就能看出多了还是少了
/v1。 - 数一数
/v1出现了几次:/v1/v1/说明你填了/v1,工具又补了一次;完全没有/v1说明工具没补,你也没填。 - 用 curl 直接请求完整地址,确认服务本身没问题,再回头调工具配置。
- 确认协议对得上:给 Anthropic 协议的工具填了 OpenAI 兼容的地址(或反过来),也会 404 或 400。
小结
记住一句话:OpenAI 系填到 /v1,Anthropic 和 Gemini 系填根地址,要求完整地址的就填到底。NiceAI 的具体写法见 接口地址要不要加 /v1。