2026-05-17HexSaga

OpenAI 兼容 API 是什么？看懂 base_url、API key 和 model 参数

用最小请求、配置示例和常见错误，解释 OpenAI 兼容 API 里的 base_url、API key、model、endpoint、/v1 后缀和 Chat Completions、Responses 的区别。

AI / 基础知识 AI中转站 API网关多模型 AI Token

OpenAI 兼容 API 是什么？看懂 base_url、API key 和 model 参数

很多 AI 工具在配置里都会让你填三样东西：

API key
base_url
model

如果你用过 AI 中转站、第三方模型平台、本地模型网关，或者想让 Codex、聊天客户端、自动化脚本走另一个入口，经常还会看到一个说法：OpenAI 兼容 API。

它听起来像一个正式认证，其实更像一种接口约定。简单说：服务端尽量按照 OpenAI API 的请求方式来接收参数，让原本支持 OpenAI 的工具可以少改代码，甚至只改地址和 key，就能调用另一个平台。

这篇不讲抽象协议，直接从一个最小请求开始。

先看一个最小请求

下面是一个典型的 Chat Completions 风格请求。域名、key 和模型名都是占位示例，不是真实服务。

curl https://relay.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-example",
    "messages": [
      {
        "role": "user",
        "content": "用一句话解释什么是 OpenAI 兼容 API"
      }
    ]
  }'

这个请求里有四个关键点：

https://relay.example.com/v1 是基础地址，也就是常说的 base_url。
/chat/completions 是具体接口路径，也就是 endpoint。
Authorization: Bearer sk-your-api-key 里放的是 API key。
"model": "gpt-example" 指定这次要调用哪个模型。

把这四件事分清，OpenAI 兼容 API 的大部分配置问题就清楚了。

API key：证明你是谁，也决定账单从哪里扣

API key 是访问服务的密钥。它通常长得像 sk-...，但前缀不重要，真正重要的是它由哪个平台签发。

如果你调用的是官方 OpenAI API，就使用官方账号里的 key。如果你调用的是中转站或第三方网关，就使用那个平台给你的 key。工具不会因为字段名叫 OPENAI_API_KEY 就自动帮你去 OpenAI 官方扣费；它只是把这个 key 放进请求头，发给你配置的 base_url。

常见请求头是这样：

Authorization: Bearer sk-your-api-key

几个实用原则：

不要把真实 key 写进公开仓库。
不要在文章、截图、报错日志里暴露完整 key。
一个工具能不能用，先看 key 属不属于当前 base_url 对应的平台。
如果平台支持子账号、额度限制、权限范围，最好给不同工具用不同 key。

很多“明明 key 正确却 401”的问题，本质上是 key 和地址不匹配：拿 A 平台的 key 去请求 B 平台的地址。

base_url：工具把请求发到哪里

base_url 是基础地址，也可以叫 API base、endpoint base、OpenAI base URL。它决定工具最终把请求发给谁。

比如：

base_url = https://relay.example.com/v1

工具内部再拼上具体接口：

/chat/completions

最终请求地址就是：

https://relay.example.com/v1/chat/completions

这也是为什么改 base_url 可以让很多工具走中转站。工具本来会向 OpenAI 风格接口发送 JSON；你把基础地址换成中转站，中转站只要实现了对应的 OpenAI 兼容接口，就能接住这类请求。

中转站收到请求后，通常会做几件事：

校验你的 API key。
读取 model 参数。
根据模型名决定路由到哪个后端模型或供应商。
记录用量并扣除额度。
把结果按兼容格式返回给工具。

对工具来说，请求格式没有大变；变的是请求被送到哪个入口。

model：你要用哪个模型，不一定是官方模型名

model 是本次请求使用的模型 ID。

在官方 API 里，它可能是官方模型名。在中转站或第三方网关里，它可能是平台自己定义的模型别名，也可能映射到某个真实上游模型。

例如：

{
  "model": "gpt-example",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ]
}

配置时不要猜模型名。最稳的做法是打开平台后台，看它给出的真实 model id，然后原样填进去。

如果模型名填错，常见结果是：

返回 model not found。
返回 invalid model。
请求能发出去，但被平台路由到默认模型。
工具报一个很泛的请求失败错误。

所以排查时不要只盯着 key。base_url、key、model 三个值必须属于同一个服务入口。

endpoint：base_url 后面那段具体路径

endpoint 是具体 API 路径。你可以把它理解成“这次要做什么”。

常见路径包括：

/v1/chat/completions
/v1/responses
/v1/models

如果一个工具让你填的是完整接口地址，可能要包含 /v1/chat/completions。但更多工具只让你填 base_url，它自己会在后面拼 /chat/completions 或 /responses。

所以配置时要先看清楚字段含义：

字段叫 base_url：通常填到 /v1 为止。
字段叫 endpoint：可能要填完整路径。
字段已经写明 Responses endpoint：就要确认平台支持 /v1/responses。
字段写的是 OpenAI compatible URL：要看该工具文档说明是否包含 /v1。

不同工具叫法不完全一致，不能只凭字段名硬套。

/v1 后缀到底要不要写？

这是最容易让人卡住的地方。

OpenAI 风格 API 的完整路径通常带 /v1，例如：

https://relay.example.com/v1/chat/completions

但配置项里要不要写 /v1，取决于工具怎么拼路径。

常见情况有三种：

工具要求 base_url 包含 /v1，然后它拼 /chat/completions。
工具要求你只填域名，内部自动拼 /v1/chat/completions。
平台给你的地址已经是完整兼容入口，文档会明确写 https://relay.example.com/v1。

填错时经常会出现这类地址：

https://relay.example.com/v1/v1/chat/completions
https://relay.example.com/chat/completions

前者是重复 /v1，后者是少了 /v1。结果通常是 404、接口不存在，或者工具只显示“请求失败”。

不确定时，用最小请求试一下：

curl https://relay.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-example",
    "messages": [
      {
        "role": "user",
        "content": "hello"
      }
    ]
  }'

如果这个能通，再回到工具里看它到底要求你填 https://relay.example.com 还是 https://relay.example.com/v1。

OpenAI 兼容，不等于什么都兼容

“OpenAI 兼容 API”通常表示它尽量兼容 OpenAI API 的一部分约定，比如：

使用 HTTP JSON 请求。
使用 Bearer token 认证。
使用 model 指定模型。
使用 messages 或 input 传入内容。
返回结构尽量接近 OpenAI 的响应格式。

但它不保证所有功能都完整支持。

一个平台可能只支持 /v1/chat/completions，不支持 /v1/responses。另一个平台可能支持文本聊天，但不支持图片、文件、工具调用、流式输出，或者只兼容其中一部分字段。

所以“OpenAI 兼容”更像一个范围，不是一个开关。配置工具前，最好确认三件事：

这个工具使用的是 Chat Completions 还是 Responses。
这个平台是否支持对应 endpoint。
这个平台要求的模型名和参数写法是什么。

Chat Completions 和 Responses 有什么区别？

日常配置里最常见的是两个接口。

Chat Completions

路径通常是：

/v1/chat/completions

请求主体通常使用 messages：

{
  "model": "gpt-example",
  "messages": [
    {
      "role": "user",
      "content": "写一个简短标题"
    }
  ]
}

这是很多聊天客户端、旧 SDK、脚本和中转平台最熟悉的格式。它的概念很直接：给模型一组对话消息，让模型继续回答。

Responses

路径通常是：

/v1/responses

请求主体可以是这种风格：

curl https://relay.example.com/v1/responses \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-example",
    "input": "写一个简短标题"
  }'

Responses 更像统一入口，一些新工具、Agent 工具或代码助手会明确要求 Responses 兼容。比如你看到某个工具配置里有 wire_api = "responses" 之类的选项，就说明它会请求 /v1/responses，不是 /v1/chat/completions。

实用判断很简单：

工具说它用 Chat Completions：平台要支持 /v1/chat/completions。
工具说它用 Responses：平台要支持 /v1/responses。
平台只说“OpenAI 兼容”：最好再确认它兼容到哪一个接口。

一个配置长什么样

很多工具最终都可以简化成这三个值：

OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://relay.example.com/v1
OPENAI_MODEL=gpt-example

也可能写成 JSON：

{
  "apiKey": "sk-your-api-key",
  "baseURL": "https://relay.example.com/v1",
  "model": "gpt-example"
}

或者写在某个工具自己的配置文件里：

model = "gpt-example"

[provider]
base_url = "https://relay.example.com/v1"
api_key_env = "OPENAI_API_KEY"

不同工具字段名会变化，但本质仍然是：

key 负责认证。
base_url 负责入口。
model 负责选择模型。
endpoint 由工具或你自己拼出来。

为什么这对中转站和多模型工具很重要？

OpenAI 兼容 API 的价值在于降低接入成本。

如果每个模型平台都要求完全不同的 SDK、不同的请求格式、不同的返回结构，工具开发者就要为每个平台单独适配。OpenAI 兼容接口把很多基础约定统一起来，工具只要会发 OpenAI 风格请求，就能比较容易地接入更多平台。

对普通用户来说，最直接的好处是：

聊天客户端可以切换不同模型入口。
Codex、代码助手、Agent 工具可以通过配置使用中转 API。
脚本可以只改环境变量，不必重写请求逻辑。
一个余额或网关后面可以接多个模型。

如果你正在配置 Codex 或 Claude Code 这类工具，可以接着看这篇更偏实操的配置文：如何配置 Codex 和 Claude Code 使用中转 API。

如果你还在比较中转站、官方 API 和会员的选择，可以看：AI 中转站、官方 API、订阅会员，到底该怎么选？。

如果你还不清楚请求里的 token 为什么会影响额度和费用，可以先看：AI Token 是什么？一篇讲清楚。

常见排查顺序

遇到“工具连不上”“请求失败”“模型不可用”时，可以按这个顺序查：

确认 base_url 是否多了或少了 /v1。
确认 API key 属于这个 base_url 对应的平台。
确认 model 是平台后台给出的真实 model id。
确认工具使用的是 Chat Completions 还是 Responses。
用最小 curl 请求绕开工具，先验证平台接口能不能通。
再回到工具配置里检查字段名和路径拼接规则。

不要一上来就换模型、换客户端、重装工具。大多数 OpenAI 兼容 API 的配置问题，最后都落在这几个值上。

一句话总结

OpenAI 兼容 API 不是“只能访问 OpenAI”，也不是“所有平台完全一样”。它的意思是：服务端提供一套接近 OpenAI API 的请求和响应格式，让工具可以通过 API key、base_url、model 和对应 endpoint 接入不同模型平台。

真正配置时记住一句话就够了：key 决定身份，base_url 决定入口，model 决定模型，endpoint 决定这次调用什么能力。