---
title: "base_url 是什么，怎么填"
description: "base_url 是 SDK 拼请求的根地址，填错就会 404。这页讲清末尾斜杠与 /v1 的常见错误、环境变量写法，以及怎么用 curl 先验证再换 SDK。"
updated: 2026-11-13
canonical: https://docai.cc/concepts/base-url/
markdown_mirror: https://docai.cc/concepts/base-url.md
---
## 它是什么

base_url 是 SDK 拼请求时用的根地址。它不是完整的接口地址，而是「域名加版本前缀」这一层；SDK 会在它后面接上具体路径，比如 `/chat/completions`。

```text
base_url     https://api.example.com/v1
最终请求     https://api.example.com/v1/chat/completions
```

区分三个东西：[endpoint](/concepts/endpoint/) 是最终被请求的完整地址；base_url 是它的前缀；API key 放在请求头里，和地址是两回事。

## 怎么工作

SDK 内部做的拼接大致是 `base_url + 路径`。官方的 OpenAI SDK 默认指向官方地址，换供应商时改这一项就够了，前提是路径规则一致。

多数 SDK 支持用环境变量配置，例如 `OPENAI_BASE_URL`。key 用 `OPENAI_API_KEY` 这类变量注入，不要写进仓库。变量名各家 SDK 不完全一样，官方未说明时以该 SDK 的文档为准。

真正的问题出在边界情况：两段路径怎么接、斜杠怎么处理、版本段由谁补。不同 SDK 的拼接实现不同，所以同一个地址在 curl 里能通，放进代码里未必能通。

## 怎么填

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.example.com/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)
```

两个最常见的错误：

- **漏掉 `/v1`**：厂商文档给的根地址通常带版本段。少一段，请求会打到别的路径，常见结果是 404 或一段 HTML。
- **多写 `/v1`**：有的 SDK 自己会补版本段，于是拼成 `/v1/v1/chat/completions`。先看文档，再用 curl 验证，不要靠猜。

末尾斜杠一般不影响，但有的实现会拼出双斜杠，个别服务不认。统一写成不带末尾斜杠，最省事。

## 先用 curl 验证

换 SDK 之前，先用 curl 打一次，把地址问题和代码问题分开：

```bash
curl -sS -i https://api.example.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

看三样：状态码、`Content-Type`、响应体是不是你要的 JSON。404 先查路径，401 先查 key 和请求头格式。curl 通了再换 SDK；不通就别先怀疑代码。报错怎么读见[读一个 API 报错](/learn/read-an-error/)。

## 把 key 发到哪，风险就在哪

base_url 填谁的域名，你的 API key 就会随着请求头发给谁。域名看起来像官方的，不代表真属于官方；打着「免费中转」旗号的地址，可能记录并转卖 key。

几条硬性判断：只走 HTTPS；确认域名归属；不要用来源不明的中转地址；给不同用途分配不同的 key，出问题时能单独吊销。完整做法见 [API key 怎么管](/concepts/api-key/)。

## 常见误解

- **「base_url 就是完整接口地址」**：不是。它是根，SDK 会往后接路径。
- **「填域名就够了」**：通常还要带版本段，具体以厂商文档为准。
- **「地址对了模型名随便填」**：模型名由这家厂商自己定，换地址不换模型名照样报错。
- **「本地调试可以先用 HTTP」**：调本机服务可以，发真实 key 时不要走明文。

## 延伸阅读

- 完整地址是什么：[什么是 endpoint](/concepts/endpoint/)
- 第一次调用：[发出第一个 API 请求](/learn/first-api-call/)