什么是 OpenAI 兼容 API？Base URL、API Key 和模型名一次讲清楚
理解 OpenAI 兼容 API 的工作方式，学会配置 Base URL、API Key、模型名，并区分 Chat Completions 与 Responses API。
你可能在 Cursor、Codex CLI、Open WebUI、Chatbox 或某个 Python 项目里见过这三个配置项：
Base URL
API Key
Model
它们之所以频繁出现，是因为越来越多 AI 服务提供 OpenAI 兼容 API。你可以继续使用熟悉的 OpenAI SDK、请求格式和工具，只需要替换接口地址、密钥与模型名，就能接入另一个服务或 API 网关。
但“兼容”并不等于“所有功能完全相同”。如果没有理解 Base URL、Endpoint、模型名和协议版本之间的关系，很容易遇到 401、404、model not found 或响应字段不匹配。
本文从实际配置出发，把 OpenAI 兼容 API 的核心概念一次讲清楚。
OpenAI 兼容 API 到底是什么意思？
OpenAI 兼容 API 指的是：服务端按照 OpenAI 常见的 HTTP 接口结构接收请求，并返回相近的 JSON 响应。
例如，聊天请求通常发送到：
POST /v1/chat/completions
请求体包含：
{
"model": "YOUR_MODEL_ID",
"messages": [
{
"role": "user",
"content": "用一句话解释 API Gateway"
}
]
}
响应通常包含：
{
"choices": [
{
"message": {
"role": "assistant",
"content": "API Gateway 是客户端与后端服务之间的统一入口。"
}
}
]
}
因此，原本使用 OpenAI SDK 的程序通常只需要修改少量配置，不必重新实现认证、消息格式、流式解析和错误处理。
一个 API 网关还可以在兼容接口背后完成：
- 多供应商模型接入；
- 统一认证与额度管理；
- 模型名称映射；
- 请求路由和故障切换；
- 使用量统计与日志；
- OpenAI、Claude、Gemini 等格式转换。
三个必须配置的值
1. Base URL：请求发到哪里
Base URL 是 SDK 或客户端发送请求的服务根地址。
使用 Nbility 的 OpenAI 兼容接口时，常见配置是：
https://api.nbility.ai/v1
OpenAI SDK 会在这个地址后继续拼接 Endpoint。例如：
Base URL: https://api.nbility.ai/v1
Endpoint: /chat/completions
最终地址: https://api.nbility.ai/v1/chat/completions
不同客户端的拼接方式可能不同。某些工具要求填写包含 /v1 的 Base URL，另一些工具会自行追加 /v1。配置前应查看该工具文档，或观察它最终请求的 URL。
常见错误包括：
https://api.example.com/v1/v1/chat/completions
https://api.example.com/chat/completions
https://api.example.com/v1/chat/completions/chat/completions
所以不要把 Base URL、API 版本和完整 Endpoint 混为一谈。
2. API Key：你是否有权调用
大多数 OpenAI 兼容接口使用 Bearer Token：
Authorization: Bearer YOUR_API_KEY
API Key 用来识别账号、Token 分组、额度与权限。它应该只保存在服务端环境变量、密钥管理系统或客户端的安全设置中。
不要：
- 把真实 Key 写进博客或截图；
- 提交到 GitHub；
- 放进公开的前端代码；
- 在日志中输出完整认证头；
- 通过聊天消息发送长期有效的生产 Key。
推荐使用环境变量：
export NBILITY_API_KEY="YOUR_API_KEY"
3. Model：具体调用哪个模型
model 是服务端识别的模型 ID，不是随意填写的展示名称。
{
"model": "YOUR_MODEL_ID"
}
同一个模型在不同平台上可能使用不同 ID，也可能通过别名映射到具体上游模型。最可靠的方式是查看当前服务的模型列表，而不是复制另一家平台文档中的名字。
可通过模型接口检查当前 Token 可见的模型：
curl https://api.nbility.ai/v1/models \
-H "Authorization: Bearer $NBILITY_API_KEY"
如果返回 model not found，优先检查：
- 模型 ID 的拼写和大小写；
- Token 是否有该模型权限；
- 客户端是否覆盖了你配置的模型名；
- 网关是否配置了模型映射；
- 当前 Endpoint 是否支持该模型。
一次请求是怎样完成的？
完整调用链可以简化为：
客户端
→ 携带 Bearer Token 发送 HTTP 请求
→ API Gateway 验证权限和请求格式
→ 路由到目标模型
→ 将上游结果转换为兼容 JSON
→ 返回客户端
以 curl 为例：
curl https://api.nbility.ai/v1/chat/completions \
-H "Authorization: Bearer $NBILITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"messages": [
{"role": "user", "content": "Hello"}
]
}'
如果这个最小请求成功，说明域名、认证、Endpoint 和模型基本可用。之后再加入长上下文、图片、工具调用和流式输出，排错会更容易。
Python 中如何配置？
安装 OpenAI SDK 后，可以自定义 base_url：
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NBILITY_API_KEY"],
base_url="https://api.nbility.ai/v1",
)
response = client.chat.completions.create(
model="YOUR_MODEL_ID",
messages=[
{"role": "user", "content": "Explain API compatibility briefly."}
],
)
print(response.choices[0].message.content)
关键不是更换 SDK，而是把 SDK 指向正确的兼容服务。
Node.js 中如何配置？
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: process.env.NBILITY_API_KEY,
baseURL: 'https://api.nbility.ai/v1',
});
const response = await client.chat.completions.create({
model: 'YOUR_MODEL_ID',
messages: [{ role: 'user', content: 'Hello' }],
});
console.log(response.choices[0].message.content);
生产环境中不要把 Key 放在浏览器端。应由后端或受控的 Serverless Function 调用 API。
Chat Completions 和 Responses API 有什么区别？
目前常见的 OpenAI 兼容协议不只有一种。
| 项目 | Chat Completions | Responses API |
|---|---|---|
| Endpoint | /v1/chat/completions | /v1/responses |
| 主要输入 | messages | input、instructions |
| 主要输出 | choices | output、output_text |
| 对话模式 | 客户端通常维护消息历史 | 可用 previous_response_id 延续 |
| 工具能力 | Function Calling | 面向工具和状态化工作流的新格式 |
| 兼容范围 | 最广，旧工具常用 | 新 SDK、Codex 等新工具更多使用 |
Chat Completions 示例：
client.chat.completions.create(
model="YOUR_MODEL_ID",
messages=[{"role": "user", "content": "Hello"}],
)
Responses API 示例：
response = client.responses.create(
model="YOUR_MODEL_ID",
input="Hello",
)
print(response.output_text)
不能把 messages 原封不动传给只接受 input 的接口，也不能假设 Responses API 一定返回 choices。客户端、Endpoint 和响应解析必须使用同一协议。
“兼容”通常兼容到什么程度？
兼容性不是非黑即白，常见层级包括：
- 基础请求兼容：模型、文本消息和普通响应可用；
- 流式兼容：支持 SSE 与增量内容；
- 工具调用兼容：支持 tools、tool calls 和结果回传；
- 多模态兼容：支持图片、音频或文件输入；
- 高级参数兼容：支持结构化输出、推理参数、缓存等；
- 错误格式兼容：SDK 能正确解析错误类型和状态码。
某个服务支持 /v1/chat/completions，不代表它支持 OpenAI 的每一个参数。部分字段可能：
- 被忽略；
- 转换为上游参数；
- 只对部分模型生效；
- 返回不支持错误；
- 因上游能力不同而表现不同。
接入前应验证你真正依赖的能力，而不是只测试一句普通聊天。
为什么同一个 SDK 能调用不同模型？
SDK 只负责构造 HTTP 请求和解析响应。它并不决定后端一定是哪一家模型。
API 网关可以读取：
{
"model": "YOUR_MODEL_ID"
}
然后把请求路由到对应上游，再将结果转换回兼容格式。对客户端来说，调用方法保持一致；对网关来说，不同模型可能使用不同协议、认证方式和响应结构。
这也是兼容接口的价值：应用代码不必为每个模型重复实现一套接入层。
最常见的配置错误
401：API Key 无效
检查 Bearer 格式、环境变量、Token 状态和服务地址。不要对 401 自动重试。
404：地址或 Endpoint 错误
检查 /v1 是否重复、是否把完整 Endpoint 填进 Base URL，以及客户端究竟请求 Chat Completions 还是 Responses API。
Model Not Found
查看 /v1/models，确认模型名与 Token 权限。不要假设不同平台使用相同模型 ID。
返回内容为空
先检查实际协议和响应字段：
Chat Completions → choices[0].message.content
Responses API → output / output_text
推理模型还可能返回推理相关字段，或者因为最大输出 Token 太小而提前结束。
流式输出失败
确认服务和客户端都支持 SSE，代理没有缓存或截断流式连接，客户端也使用了正确的事件格式。
如何判断一个服务是否真的适合迁移？
用与你的生产场景一致的测试清单：
[ ] 普通文本请求
[ ] 流式输出
[ ] 长上下文
[ ] 工具调用
[ ] JSON / 结构化输出
[ ] 图片或文件输入
[ ] 超时与取消
[ ] 401、429、5xx 错误处理
[ ] 使用量与计费统计
[ ] 目标模型权限
还应关注服务稳定性、隐私政策、日志保留、数据地域、限流、成本和支持响应，而不只是“请求能不能返回一句话”。
FAQ
Base URL 一定要带 /v1 吗？
不一定，取决于客户端如何拼接路径。OpenAI SDK 配置 Nbility 时使用 https://api.nbility.ai/v1；其他客户端可能要求服务根地址。应以客户端文档和最终请求 URL 为准。
OpenAI 兼容 API 必须使用 OpenAI 的模型吗？
不需要。兼容描述的是接口格式，不是后端模型归属。网关可以用兼容格式接入多种模型。
可以直接替换 Base URL 而不改代码吗？
基础聊天通常可以，但应验证模型名、Endpoint、流式输出、工具调用和响应字段。高级功能不一定完全兼容。
为什么同一个 Key 看不到所有模型？
模型列表可能受到 Token 分组、账号权限、地区、余额或服务策略限制。以当前 Key 调用 /v1/models 的结果为准。
Chat Completions 和 Responses API 应该选哪个？
旧工具、广泛兼容场景优先 Chat Completions；使用新 OpenAI SDK、Codex 或状态化工具工作流时，可以考虑 Responses API。最终取决于客户端和目标模型是否支持。
总结
OpenAI 兼容 API 的核心可以归纳为四件事：
Base URL 决定请求发到哪里
API Key 决定你是谁以及能调用什么
Model 决定请求路由到哪个模型
Endpoint 决定使用哪种 API 协议
先用最小请求验证这四项，再逐步加入流式、多模态和工具调用，能够避免大多数接入问题。
如果你希望用统一接口连接不同模型，可以从 Nbility API 概览、认证文档和模型列表开始。遇到错误时，再结合 API 错误码文档定位认证、路径、限流或上游问题。
