Source: https://wiki.niceai.dev/guide/tech/base-url-rules

# 同一个 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 怎么排查

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

## 小结

记住一句话：**OpenAI 系填到 `/v1`，Anthropic 和 Gemini 系填根地址，要求完整地址的就填到底**。NiceAI 的具体写法见 [接口地址要不要加 /v1](https://wiki.niceai.dev/guide/v1-404)。

## 延伸阅读

- [接口地址要不要加 /v1](https://wiki.niceai.dev/guide/v1-404)
- [客户端一览](https://wiki.niceai.dev/guide/clients/)
- [Chat Completions 与 Responses 的区别](https://wiki.niceai.dev/guide/tech/responses-vs-chat-completions)
