OpenAI API endpoint 和 base URL 有什么区别？
简答：一句话结论：base URL 是多个请求共用的 API 地址前缀，endpoint 是某个具体操作的完整接口路径。使用 SDK 时通常填写 base URL，例如以 /v1 结尾；手写 curl 请求时通常填写完整 endpoint，例如 /v1/responses。若出现 404，先检查客户端是否会自动拼接资源路径，以及你是否重复填写了 /v1。
定义：Base URL 是请求共用的协议、域名和版本前缀，endpoint 是在此基础上指向具体 API 资源的请求地址。
先记住这条公式：base URL + 资源路径 = 最终请求地址
以 OpenAI API 的一个请求地址为例：
https://api.openai.com/v1/chat/completions
- 协议：
https://，表示通过 HTTPS 发送请求。 - 主机：
api.openai.com，表示请求发送到哪个 API 服务。 - 版本前缀：
/v1，属于接口版本或公共路径的一部分。 - 资源路径：
/chat/completions，表示要调用的具体 API 资源。
因此，可以把它理解为：base URL = https://api.openai.com/v1，endpoint = /chat/completions；手写 HTTP 请求时，最终地址就是两者拼接后的完整 URL。OpenAI 的 API Reference 将 Responses 的创建操作列为 POST /responses，将 Chat Completions 的创建操作列为 POST /chat/completions，可分别查看 Responses API 参考 和 Chat Completions API 参考。
| 字段 | 作用 | 示例或填写方式 |
|---|---|---|
| Base URL | 请求共用的地址前缀 | https://api.openai.com/v1 |
| Endpoint | 具体资源和操作路径 | /responses 或 /chat/completions |
| API Key | 身份认证凭据 | 放在 Authorization: Bearer ... 请求头中 |
| Model | 请求使用的模型标识 | 以当前账户可用模型列表和模型文档为准 |
不同调用方式应该怎么填写
1. 直接使用 curl：填写完整 endpoint
手写 HTTP 请求不会替你补全资源路径，因此 URL 应直接写到具体 endpoint。下面以 Responses API 为例，模型名使用占位符，运行前请替换为当前账户可用的模型 ID：
curl https://api.openai.com/v1/responses -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_API_KEY" -d '{"model":"YOUR_MODEL_ID","input":"Say hello"}'
官方快速开始也使用完整的 /v1/responses 地址发送 POST 请求，可参考 OpenAI API Platform 文档。如果你调用 Chat Completions，则将最后的资源路径改为 /chat/completions，同时按该 endpoint 的请求体格式传入 messages。
2. Python SDK：配置 base_url，不要把资源路径写进去
Python SDK 的客户端配置使用 base_url。官方参考文档给出的自定义地址示例以 /v1 结尾，SDK 再根据 client.responses.create() 或 client.chat.completions.create() 选择资源路径：
from openai import OpenAI
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.openai.com/v1")
response = client.responses.create(model="YOUR_MODEL_ID", input="Say hello")
print(response.output_text)
不要把 https://api.openai.com/v1/responses 作为 Python SDK 的 base_url，否则 SDK 可能继续拼接资源路径，形成错误地址。Python SDK 的 base_url 和 OPENAI_BASE_URL 配置方式可核对 OpenAI Python API Reference。
3. JavaScript SDK：使用 baseURL，资源由方法决定
JavaScript SDK 的字段名称是 baseURL。下面只演示配置形状，运行前请替换 API Key 和模型 ID：
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, baseURL: "https://api.openai.com/v1" });
const response = await client.responses.create({ model: "YOUR_MODEL_ID", input: "Say hello" });
console.log(response.output_text);
官方 TypeScript API Reference 使用 baseURL 配置自定义 API 主机；浏览器端直接暴露长期 API Key 具有安全风险，密钥应放在服务端或受控运行环境中。相关配置和安全说明见 OpenAI TypeScript API Reference。
Responses、Chat Completions 和 Models 的路径怎么区分
endpoint 不是固定不变的字符串，而是由你要调用的 API 资源决定。当前官方参考中，Responses 的创建路径是 /responses，Chat Completions 的创建路径是 /chat/completions，Models 列表路径是 /models。它们都可以共享同一个 base URL，但请求方法和请求体不同。
| 用途 | 资源路径 | 常见方法 | 配置提醒 |
|---|---|---|---|
| 创建模型响应 | /responses | POST | 使用 Responses API 对应的请求体 |
| 创建聊天补全 | /chat/completions | POST | 使用 messages 等 Chat Completions 字段 |
| 列出可用模型 | /models | GET | 用于核对当前接口可见的模型 ID |
模型 ID 不等于 endpoint，也不等于 base URL。若你不确定模型是否可调用，可以先查看 List models API 返回的当前列表，再把返回的 ID 放入请求体。不要仅凭旧教程或第三方模型清单判断可用性。
出现 401、404、405 或 HTML 响应时，按顺序排查
- 先确认最终请求 URL：记录客户端真正发出的地址，重点检查是否出现
/v1/v1、重复的/responses，或者把完整 endpoint 填进了 SDK 的 base URL。 - 再确认调用方式：Responses 和 Chat Completions 的资源路径不同；创建请求通常使用
POST，把请求发成GET可能得到 405。 - 检查认证头：确认请求头是
Authorization: Bearer YOUR_API_KEY，Key 没有多余空格、截断或误用其他项目的凭据。401 通常属于认证信息问题，具体以响应体为准。 - 检查服务商兼容范围：OpenAI-compatible 接口只表示接口格式或部分协议兼容，不代表一定支持所有 Responses、Chat Completions、工具调用、流式事件、模型和字段。第三方服务的
/v1、资源路径和支持范围必须以其当前文档为准。 - 检查响应内容类型：如果返回 HTML，通常应先确认域名、端口、反向代理和路径是否指向 API 服务，而不是普通网页或管理面板；不要把 HTML 错误页当成 API JSON 响应。
OpenAI 官方错误码指南将 401 与认证问题、404 与资源不存在、429 与限流或额度相关情况分别说明；遇到问题时应同时保存 HTTP 状态码、响应体、请求时间和脱敏后的最终 URL，再对照 官方错误码指南 判断。
一条实用决策规则：直接 curl 请求填写完整 endpoint；Python SDK 填 base_url；JavaScript SDK 填 baseURL；第三方客户端的字段名称和是否包含 /v1，以该客户端或服务商文档为准。
常见问题
base URL 一定要以 /v1 结尾吗？
不一定。对于官方 OpenAI SDK，官方示例展示了以 /v1 结尾的地址；但第三方兼容服务可能把版本路径放在不同位置，也可能由客户端自动添加。是否填写 /v1，要看客户端拼接规则和服务商文档，不能只凭经验判断。
可以把 /responses 直接写进 base URL 吗？
在手写 curl 中可以把它作为完整请求 URL 的一部分；在会自动拼接资源路径的 SDK 中通常不应这样填写。SDK 的 base URL 应停在它预期的公共前缀，具体资源由调用方法决定。
OpenAI API 返回 404，一定是 API Key 错了吗？
不一定。401 更直接指向认证问题；404 应优先检查域名、版本前缀、资源路径、重复 /v1 和服务商是否支持该 endpoint。仍需结合响应体判断，不能只看状态码。
OpenAI-compatible API 能直接调用所有 OpenAI endpoint 吗？
不能直接假定。兼容实现可能只支持部分资源、字段、模型或流式协议。切换到兼容服务时，应逐项核对认证方式、base URL、资源路径、模型 ID、错误响应和流式能力。
怎么确认当前模型 ID 能不能用？
可以先调用当前接口的模型列表，或查看对应服务商的模型文档。对于 OpenAI API，可参考官方 Models API；对于兼容服务，则以该服务返回结果和当前文档为准。
参考资料与核验说明
本文按 2026 年 11 月 3 日检索到的官方文档整理。本站是非 OpenAI 官方的 API 接入指南站；官方接口、模型目录和 SDK 行为可能更新，部署前应再次核对当前 API Reference。
- OpenAI API Platform 文档
- Responses API：Create a model response
- Chat Completions API：Create chat completion
- OpenAI Python API Reference
- OpenAI TypeScript API Reference
- OpenAI API Error codes
广告：如果你需要统一管理多个 AI API 的 Base URL、Key 和模型调用配置，可查看 犀速 AI 官网 的当前接入说明，具体支持范围以页面和服务条款为准。
常见问题
base URL 和 endpoint 的核心区别是什么？
Base URL 是多个请求共用的地址前缀，endpoint 是具体资源路径；最终请求地址通常由 base URL 加资源路径组成。
Python SDK 的 base_url 应该填到哪里？
通常填 API 根或版本根，例如以 /v1 结尾的地址，不要把 /responses 或 /chat/completions 也写进去，具体以当前 SDK 文档为准。
为什么会出现 /v1/v1？
通常是客户端已经自动添加 /v1，而配置中又手动填写了一次。应查看最终请求 URL，并根据客户端拼接规则保留一个版本前缀。
OpenAI API 的 404 和 401 怎么区分？
401 优先检查 API Key、组织或项目认证信息；404 优先检查域名、base URL、资源路径和资源是否存在，最终仍要结合响应体判断。
相关阅读
- 继续看 OpenAI API 401、403、404 的分层排查
- 查看 Codex 配置 API Key 和 Base URL 的实际步骤
- 如果请求成功但流式输出中断，可继续查看流式排查指南
- 浏览更多 AI API 接入与错误诊断文章