OpenAI API Base URL 是什么？官方地址与配置方法

更新于 2026-11-01 · soleapi.cyou

简答：OpenAI 官方 API Base URL 通常是 https://api.openai.com/v1。直接调用 HTTP API 时，应在它后面继续拼接具体 endpoint，例如 /models 或 /responses；使用官方 SDK 时，通常只配置 Base URL，让 SDK 自动拼接资源路径。最短验证路径是：确认 Key、确认 Base URL 只包含一次 /v1，再请求 /v1/models。

定义：Base URL 是客户端发送 API 请求时使用的基础地址，endpoint 是在基础地址后追加的具体资源路径，完整请求 URL 则是二者拼接后的最终地址。

先记住准确地址：Base URL、endpoint 和完整 URL

本文是面向开发者的独立配置说明，不代表 OpenAI 官方网站。对于 OpenAI 官方 API，当前文档示例使用的基础地址是 https://api.openai.com/v1。官方 API 总览同时说明，REST API 的主版本是 v1，请求需要使用 Bearer 认证。可参考 OpenAI API 总览。

因此，直接请求模型列表时，完整地址是 https://api.openai.com/v1/models；调用 Responses API 时，完整地址通常是 https://api.openai.com/v1/responses。不要把完整请求 URL 再当成 SDK 的 Base URL，否则客户端可能继续追加资源路径。

最重要的判断：如果客户端配置项叫 base_url 或 baseURL，先确认它会不会自动追加 /models、/responses 等路径。直接使用 curl 时写完整 URL；使用 SDK 时通常只写 Base URL。

三步完成首次验证：Key、地址、最小请求

1. 确认凭据：将 API Key 放在服务器环境变量中，不要写入网页、移动端应用或公开代码仓库。OpenAI 官方文档明确提醒，API Key 属于秘密信息，应通过环境变量或密钥管理服务加载，不能暴露在浏览器或客户端代码中。参考 官方认证说明。
2. 确认 Base URL：官方直连使用 https://api.openai.com/v1。如果使用兼容网关、企业网关或其他 OpenAI-compatible 服务，必须以该服务自己的文档为准，不能自动套用 OpenAI 官方地址。
3. 发送最小请求：先用模型列表请求确认域名、路径和 Key 是否基本可用，再测试具体模型调用。模型是否可用仍取决于账号、项目权限和服务端当前配置。

Bash、macOS、Linux 或 WSL：

export OPENAI_API_KEY="你的API_KEY"
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY"

PowerShell：

$env:OPENAI_API_KEY="你的API_KEY"
curl.exe https://api.openai.com/v1/models `
-H "Authorization: Bearer $env:OPENAI_API_KEY"

Windows CMD：

set OPENAI_API_KEY=你的API_KEY
curl.exe https://api.openai.com/v1/models -H "Authorization: Bearer %OPENAI_API_KEY%"

成功判定不是“网页能打开”，而是服务返回结构化 JSON，并且 HTTP 状态码表示请求被正常处理。若返回 401，优先检查 Key 和 Bearer 格式；若返回 404，优先检查域名、路径和服务是否真的提供该 endpoint。

Python、JavaScript SDK 应该怎么填写 Base URL

官方 SDK 通常会把资源路径交给 SDK 处理，因此 Base URL 不应重复写成某个具体 endpoint。OpenAI Python SDK 当前的路由优先级是：显式传入的 base_url 优先，其次读取 OPENAI_BASE_URL，最后使用默认地址 https://api.openai.com/v1，具体逻辑可查看其 官方 Python SDK 路由说明。

Python：显式配置

执行前提：已安装当前版本的官方 openai Python 包，并将 YOUR_MODEL_ID 替换为账号可用的模型 ID。

from openai import OpenAI

client = OpenAI(
api_key="你的API_KEY",
base_url="https://api.openai.com/v1",
)

response = client.responses.create(
model="YOUR_MODEL_ID",
input="Say hello in one sentence.",
)

print(response.output_text)

JavaScript：使用 baseURL

JavaScript SDK 的字段名通常是 baseURL，而不是 Python 的 base_url。示例使用服务器端 Node.js，不能直接放进浏览器前端。

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 in one sentence."
});

console.log(response.output_text);

官方快速入门提供了 API Key、SDK 和首次请求的基本流程，可参考 OpenAI Developer quickstart。模型 ID 不建议凭记忆填写；如果不确定，应先查看当前模型文档或通过模型列表确认账号可见的模型。

OPENAI_BASE_URL 环境变量怎么用

如果项目或 SDK 支持环境变量，可以统一设置 Base URL，避免把地址写入多个配置文件。官方 Python SDK 文档显示，在没有显式 base_url 时会读取 OPENAI_BASE_URL，再回退到默认地址。

Bash：export OPENAI_BASE_URL="https://api.openai.com/v1"

PowerShell：$env:OPENAI_BASE_URL="https://api.openai.com/v1"

CMD：set OPENAI_BASE_URL=https://api.openai.com/v1

如果显式代码中已经写了另一个 base_url，不要假设环境变量一定能覆盖它。排查时先搜索项目配置、启动脚本和部署环境，确认到底是哪一个值生效。对于使用网关的场景，环境变量可以填写网关文档给出的 Base URL，例如 https://gateway.example.com/v1；其中域名、路径、鉴权头和模型 ID 都必须以该网关文档为准。

官方 API、OpenAI-compatible 服务和 Azure 地址不要混填

Azure 的地址不能直接替换成 OpenAI 官方地址。Microsoft 官方文档显示，Azure OpenAI v1 使用 /openai/v1/ 路径，并将部署名放在请求的 model 字段中；该路径使用隐式版本控制时不需要额外添加 api-version。参考 Microsoft Foundry endpoint 文档。

同理，mTLS、区域端点、企业代理和其他特殊路由也不能只凭“看起来像 OpenAI API”来填写。官方 Python SDK 的文档还列出了 mTLS 等特殊地址，说明这类配置涉及证书、传输层和固定 API origin，应按对应文档单独配置，而不是把它们当成普通 API Key 请求。

Base URL 常见错误与排查顺序

• 出现 /v1/v1：通常是 Base URL 已经包含 /v1，客户端配置项或自定义请求代码又追加了一次。检查最终请求 URL，确保 Base URL 和 endpoint 的职责只分配一次。
• 末尾斜杠不一致：不同 SDK 对路径合并和斜杠的处理可能存在差异。优先使用该 SDK 官方示例的写法，并避免手工拼接出连续斜杠或缺少分隔符的路径。
• 域名正确但 404：检查是否把 /responses、/chat/completions 或 /models 写成了服务并不支持的路径；兼容服务不一定实现全部官方 API surface。
• 401：确认使用的是正确 Key，格式是 Authorization: Bearer 你的Key，并检查环境变量是否在当前终端或进程中生效。
• 模型报错：模型 ID、Azure 部署名和兼容网关模型名可能不是同一套命名。先获取或查看当前服务可用模型，再替换示例中的 YOUR_MODEL_ID。
• 前端请求失败或 Key 泄露：不要把真实 Key 放在浏览器代码、公开仓库、截图或前端打包产物中。正确做法是由自己的后端保存 Key，再由后端调用模型服务。

建议固定采用“凭据→Base URL→路径→模型→最小请求”的顺序排查，不要看到单个状态码就直接判断是余额、权限或服务状态问题。最终应结合响应体、请求 URL、请求头脱敏信息和服务文档共同判断。

常见问题

OpenAI API Base URL 官方地址到底是什么？

官方 API 常用 Base URL 是 https://api.openai.com/v1。直接使用 curl 时，在它后面追加 /models 或 /responses；使用 SDK 时通常把它作为 base_url 或 baseURL，由 SDK 自动追加具体资源路径。

Base URL 需要填写 /v1 吗？

对于官方 OpenAI API，SDK 默认地址和官方请求示例都包含 /v1，因此通常应填写一次。关键不是机械地添加，而是确认客户端是否会自动追加路径，避免最终 URL 变成 /v1/v1。

OpenAI-compatible API 可以直接使用官方 Base URL 吗？

不能直接假设。兼容服务应使用其文档提供的 Base URL、认证方式、模型 ID 和支持的 endpoint。它可能只兼容部分 OpenAI API 格式，具体行为需要以服务文档和实际响应为准。

Python 的 base_url 和 JavaScript 的 baseURL 有什么区别？

它们表达的是同一个概念，但字段命名不同：Python 官方 SDK 使用 base_url，JavaScript SDK 常用 baseURL。两者都应配置基础地址，不要把完整的 /responses 请求地址当成 Base URL。

为什么请求 OpenAI API 返回 404？

先检查最终请求 URL 是否重复了 /v1、是否漏写了 endpoint、是否使用了错误域名，再确认当前服务是否支持该 API 路径。若使用 Azure 或兼容网关，还要改用对应平台的地址格式和模型命名。

相关阅读

• API Key 安全存储与泄露处置指南
• Cline 中配置 Provider、Base URL 与模型
• Gemini API 接入 OpenAI 兼容客户端
• GPT API 401 错误排查步骤

参考资料

1. OpenAI API Reference：API Overview
2. OpenAI Developer quickstart
3. openai-python：Security model 与 Base URL 路由说明