OpenAI兼容API:它是什么、谁支持它以及如何安全切换
目录:
快速答案: OpenAI 兼容 API 接受与 OpenAI API 相同的请求并返回相同的响应。
因此,官方 OpenAI SDK 及基于它构建的工具可以通过更改三个值来调用其他模型:基础 URL、API 密钥和模型名称。Anthropic、Google Gemini、Mistral、Groq、DeepSeek、OpenRouter、Ollama、vLLM 等许多其他公司都提供了这样的接口。
-
保持不变的: 请求结构、SDK 和大部分代码。
-
可能出现问题的: 严格 JSON 模式、工具调用、流式处理细节、被忽略的参数、错误消息和速率限制标头。
-
原生 SDK 还是兼容 API? 使用兼容 API 快速切换和比较。需要供应商专有功能时使用原生 SDK。
-
切换前: 运行简短的冒烟测试并保留一行回滚命令。
大多数 AI 应用都从 OpenAI 的 API 开始,因此大多数代码都是为 OpenAI SDK 编写的。
OpenAI 兼容 API 让你保留这些代码,并将相同的请求发送到 Claude、Gemini、开源模型或你自己的服务器。
这就是为什么切换模型只需几分钟,而不是重写整个代码。
不过,"兼容"并不意味着"完全相同",这些差异会在生产环境中显现出来。
本指南解释了 OpenAI 兼容 API 的工作原理、哪些供应商提供了兼容 API、切换时会出现哪些问题,以及如何在信任某个供应商之前对其进行测试。
如果你希望通过一个密钥和一张账单访问多个供应商,ScriptRun 的 OpenAI 兼容 API 可与你已有的 OpenAI SDK 配合使用。
什么是 OpenAI 兼容 API
OpenAI 兼容 API 是复制 OpenAI API 接口的任何 API:相同的端点、相同的 JSON 请求和响应格式,以及相同的 Bearer 令牌身份验证。
由于格式相匹配,任何为 OpenAI 构建的客户端都可以与它通信。
在所有 OpenAI 兼容 API 端点中,几乎每个供应商都复制的是聊天完成 /v1/chat/completions,因为这是大多数 SDK 和框架调用的。
许多还复制了 /v1/models 和 /v1/embeddings。对于较新的端点(如 Responses、文件、批量处理或音频)的支持差异更大。
OpenAI 的格式成为了通用标准,因为它率先出现,几乎每个框架都采纳了它:LangChain、LlamaIndex、Vercel AI SDK、n8n 等等。
模型供应商复制了它,以便开发人员可以尝试他们的模型而不用学习新的 SDK。
自托管服务器如 vLLM、Hugging Face 文本生成推理 (TGI)、Ollama 和 LM Studio 复制了它,以便本地模型可以接入相同的工具。
OpenAI 兼容 API 的工作原理
通过更改三个值,可以将 OpenAI SDK 指向不同的服务器:
-
基础 URL: 供应商的端点,例如 Gemini 的 https://generativelanguage.googleapis.com/v1beta/openai/。
-
API 密钥: 供应商的密钥,而不是你的 OpenAI 密钥。
-
模型名称: 该供应商的模型 ID,如 gemini-3.8-flash。
其他所有内容(包括你的消息、参数和响应处理)保持不变。这是使用 Google 记录的 Gemini 端点用三种语言编写的相同请求。
Python
from openai import OpenAI
client = OpenAI(
api_key="GEMINI_API_KEY",
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[
{
"role": "user",
"content": "Explain an OpenAI compatible API in one sentence."
}
],
)
print(response.choices[0].message.content)
Node.js
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.GEMINI_API_KEY,
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});
const response = await client.chat.completions.create({
model: "gemini-3.8-flash",
messages: [
{
role: "user",
content: "Explain an OpenAI compatible API in one sentence."
}
],
});
console.log(response.choices[0].message.content);
curl
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"messages": [
{
"role": "user",
"content": "Hello"
}
]
}'
📌 提示:按照供应商文档记录的方式准确复制每个基础 URL。
OpenAI SDK 会将 /chat/completions 等路径添加到你提供的任何内容,所以缺少或多余的 /v1 是最常见的设置错误。
哪些供应商提供 OpenAI 兼容 API
几乎所有主要的模型供应商、云平台、网关和自托管推理服务器现在都提供了一个。
Groq OpenAI 兼容 API、DeepSeek OpenAI 兼容 API 和 Together AI OpenAI 兼容端点都接受相同的请求;只有基础 URL、密钥和模型会改变。
这些是记录的基础 URL。
| 供应商 | 类型 | OpenAI 兼容基础 URL |
|---|---|---|
| OpenAI | 参考 API | https://api.openai.com/v1 |
| Anthropic (Claude) | 模型供应商 | https://api.anthropic.com/v1/ |
| Google Gemini API | 模型供应商 | https://generativelanguage.googleapis.com/v1beta/openai/ |
| Mistral AI | 模型供应商 | https://api.mistral.ai/v1 |
| DeepSeek | 模型供应商 | https://api.deepseek.com |
| xAI (Grok) | 模型供应商 | https://api.x.ai/v1 |
| Groq | 推理供应商 | https://api.groq.com/openai/v1 |
| Together AI | 推理供应商 | https://api.together.ai/v1 |
| Fireworks AI | 推理供应商 | https://api.fireworks.ai/inference/v1 |
| Azure OpenAI / Microsoft Foundry | 云平台 | https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ |
| Amazon Bedrock | 云平台 | https://bedrock-runtime.{region}.amazonaws.com/openai/v1 |
| OpenRouter | 网关 | https://openrouter.ai/api/v1 |
| Ollama | 本地服务器 | http://localhost:11434/v1/ |
| LM Studio | 本地服务器 | http://localhost:1234/v1 |
| vLLM | 自托管服务器 | http://localhost:8000/v1 |
Anthropic 和 Gemini 的基础 URL 已根据它们自己的文档进行了验证,日期为 2026 年 11 月 13 日。
其他来自 DevelopersDigest 的兼容性参考,已于 2026 年 10 月 18 日根据每个供应商的文档进行验证。
供应商可能会更改这些,所以在部署前检查文档。
兼容并不等于相同:切换时会出现什么问题
OpenAI API 兼容意味着供应商接受 OpenAI 的格式。它不保证 OpenAI 的行为。
简单的调用几乎在任何地方都能工作;问题出现在生产应用依赖的功能中。
| 领域 | 通常工作的 | 经常不同的 |
|---|---|---|
| 基础聊天 | 消息输入、选择输出 | 系统消息的处理方式 |
| 参数 | temperature、max_tokens、stop | 不支持的字段(seed、logprobs、penalties)通常被静默忽略,而不是被拒绝 |
| 结构化输出 | 许多模型上的基础 JSON 输出 | 接受的 response_format 类型以及是否强制执行"严格"模式 |
| 工具调用 | 定义工具并获得回调 | 严格参数模式、并行调用、tool_choice 选项 |
| 流式处理 | 令牌到令牌的块 | 块边界、空选择、使用情况是否在最后到达 |
| 输入 | 文本,通常是图像 | 音频、文件和 PDF |
| 错误和限制 | HTTP 状态代码 | 错误消息和速率限制标头(见我们的 OpenAI API 速率限制 指南) |
| 其他端点 | 模型列表,通常是嵌入 | Responses API、批量处理、文件、音频 |
Anthropic OpenAI 兼容 API:有什么不同
Anthropic 对其层的说明异常清晰。其文档说该层"主要用于测试和比较模型功能,对大多数用例而言不被视为长期或生产就绪的解决方案"。
它们还列出了具体差异:
-
函数调用的 strict 参数被忽略,所以工具参数不保证与你的模式匹配。
-
response_format 仅接受带 strict: true 的 json_schema;json_object 或 text 返回 400 错误。
-
音频和文件输入返回 400 错误,提示缓存不通过此层支持。
-
logprobs、seed、presence_penalty 和 frequency_penalty 等字段被静默忽略。
-
错误格式与 OpenAI 匹配,但详细错误消息不匹配,某些速率限制标头的名称不同。
Gemini OpenAI 兼容 API:有什么不同
Google 的层涵盖范围更广:聊天、流式处理、函数调用、图像和音频理解、结构化输出、嵌入和部分批量 API。
Gemini 专有选项(如思考设置和缓存内容)放在 extra_body 中。Google 仍然将 OpenAI 库支持标记为测试版,并表示:"如果你还没有使用 OpenAI 库,我们建议你直接调用 Gemini API。"
来源:Google,Gemini API OpenAI 兼容性。
OpenAI 兼容 API 或供应商的原生 SDK
两者都没有总是对的。根据你的需求选择。
| 选择 OpenAI 兼容 API 时… | 选择原生 SDK 时… |
|---|---|
| 你的应用已经使用 OpenAI SDK 或基于它构建的框架 | 你从一个供应商开始全新开发 |
| 你想快速比较模型或切换供应商 | 你需要供应商专有功能,如 Anthropic 的提示缓存和 PDF 支持,或 Gemini 的基础和缓存选项 |
| 你使用多个供应商并想要一个代码路径 | 你需要兼容层不保证的行为 |
| 你想要供应商间的故障转移而无需新的集成代码 | 供应商说其层不用于生产,如 Anthropic 所做 |
许多团队两者都做。
他们对大多数流量使用 OpenAI 兼容 API,并对需要它的一两项功能使用原生 SDK。
直接到每个供应商,或通过一个网关
你可以将你的应用指向每个供应商的兼容端点,或指向为许多供应商提供一个 OpenAI 兼容端点的网关。
| 直接到每个供应商 | 一个 OpenAI 兼容网关 | |
|---|---|---|
| 设置 | 每个供应商一个帐户、密钥和计费 | 一个帐户、一个密钥、一张账单 |
| 切换模型 | 更改基础 URL、密钥和模型 | 更改模型名称 |
| 中断和速率限制 | 你构建重试和故障转移 | 通常内置(检查如何) |
| 延迟 | 没有额外跳转 | 一个额外网络跳转 |
| 依赖 | 每个供应商 | 每个供应商加网关 |
| 数据路径 | 你的应用到供应商 | 你的应用到网关到供应商 |
一旦你使用多个供应商、需要故障转移或想在一个地方进行支出和限制管理,网关就会有所回报。
询问任何网关(包括 ScriptRun)它增加多少延迟、其正常运行时间记录是什么,以及它如何处理你的数据。
关于请求如何在模型之间路由,见我们的 LLM 路由器 指南。
在五分钟内测试任何 OpenAI 兼容 API
在相信"兼容"标签之前,不要忘记测试你的应用使用的功能。
这个脚本针对任何供应商检查五件事:带使用数据的基础聊天、流式处理、工具调用、严格 JSON 模式和错误处理。
设置三个环境变量 - LLM_BASE_URL、LLM_API_KEY 和 LLM_MODEL;运行脚本,读取 PASS 和 FAIL 行。
Python
import json
import os
from openai import OpenAI
client = OpenAI(
base_url=os.environ["LLM_BASE_URL"],
api_key=os.environ["LLM_API_KEY"]
)
MODEL = os.environ["LLM_MODEL"]
def basic_chat():
r = client.chat.completions.create(
model=MODEL,
messages=[{"role": "user", "content": "Reply with the word OK."}],
max_tokens=10
)
assert r.choices[0].message.content, "empty reply"
assert r.usage and r.usage.total_tokens > 0, "no usage data"
def streaming():
stream = client.chat.completions.create(
model=MODEL,
messages=[{"role": "user", "content": "Count to 3."}],
stream=True
)
text = "".join(
c.choices[0].delta.content or ""
for c in stream if c.choices
)
assert text, "empty stream"
def tool_calling():
tool = {
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the weather for a city",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string"}
},
"required": ["city"]
}
}
}
r = client.chat.completions.create(
model=MODEL,
messages=[
{"role": "user", "content": "What's the weather in Paris?"}
],
tools=[tool]
)
call = r.choices[0].message.tool_calls[0]
assert json.loads(call.function.arguments)["city"], "no city argument"
def json_schema():
schema = {
"type": "object",
"properties": {
"answer": {"type": "string"}
},
"required": ["answer"],
"additionalProperties": False
}
r = client.chat.completions.create(
model=MODEL,
messages=[{"role": "user", "content": "Say hello."}],
response_format={
"type": "json_schema",
"json_schema": {
"name": "reply",
"schema": schema,
"strict": True
}
}
)
assert "answer" in json.loads(r.choices[0].message.content)
def error_handling():
try:
client.chat.completions.create(
model="model-that-does-not-exist",
messages=[{"role": "user", "content": "hi"}]
)
except Exception as err:
status = getattr(err, "status_code", None)
assert status and 400 <= status < 500, f"unexpected error: {err!r}"
return
raise AssertionError("no error for an unknown model")
for name, test in [
("basic chat + usage", basic_chat),
("streaming", streaming),
("tool calling", tool_calling),
("strict JSON schema", json_schema),
("error handling", error_handling)
]:
try:
test()
print(f"PASS {name}")
except Exception as err:
print(f"FAIL {name}: {err}")
FAIL 并不总是排除某个供应商。它告诉你代码的哪一部分需要变通方法,或哪些请求应该保留在另一个模型上。
迁移检查列表:在不破坏生产的情况下切换
-
列出你使用的内容。 端点、参数、工具、JSON 模式、流式处理、图像和文件。
-
检查供应商的兼容性页面 了解每一项,特别是被静默忽略的字段。
-
运行冒烟测试 使用你真实的提示和模型。
-
将配置移到环境变量中: 基础 URL、密钥和模型。切换回去只是配置更改,不需要部署。
-
比较真实请求样本的输出: 质量、延迟和每 1,000 个请求的成本。
-
逐步推出。 从少量流量或内部功能开始。
-
监视错误和速率限制, 并在前几周将旧供应商保留为备用方案。
使用 ScriptRun 的 OpenAI 兼容 API
ScriptRun 的 Open API 为来自 OpenAI、Anthropic (Claude) 和 Google (Gemini) 的模型提供了一个 OpenAI 兼容端点和一个 API 密钥。
你保留 OpenAI SDK 并更改两行:
from openai import OpenAI
client = OpenAI(
base_url="SCRIPTRUN_BASE_URL", # from your ScriptRun dashboard
api_key="YOUR_SCRIPTRUN_KEY",
)
response = client.chat.completions.create(
model="MODEL_ID", # any model available in ScriptRun
messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
除兼容格式外,你还可以获得:
-
一个帐户而不是许多: 无需与每个供应商进行单独的注册或 KYC 检查,只需一张账单。
-
智能路由和故障转移: 按质量、成本和上下文大小选择模型,在中断期间自动在供应商之间切换。
-
内置可靠性: 带退避的重试和请求级幂等性,因此重试的调用不会被处理两次。
-
控制: 每项目密钥、限制和配额。
-
全球团队的访问和计费: 无需 VPN 的访问、卡、加密货币和电汇,以及公司的合同和发票。
-
需要时的工作流: 工作流 API 为多步 AI 任务添加分支、webhook、超时和重试。
适用与任何网关相同的注意:在将生产流量转移之前,使用你自己的提示针对 ScriptRun 运行上面的冒烟测试。
获取 ScriptRun API 密钥 并使用你已有的代码尝试。
关于OpenAI兼容API的常见问题
Claude API 是否与 OpenAI 兼容?
是的。Anthropic在https://api.anthropic.com/v1/提供了OpenAI SDK兼容性层。Anthropic表示这主要用于测试和比较模型,而不是长期生产使用,并且某些功能的行为方式不同。为了获得完整的Claude功能,请使用原生API或支持Claude的网关。
Gemini API 是否与 OpenAI 兼容?
是的。将基础 URL 设置为 https://generativelanguage.googleapis.com/v1beta/openai/,使用 Gemini API 密钥和 Gemini 模型名称。Google 将此支持标记为测试版。
Ollama API 是否与 OpenAI 兼容?
是的。Ollama OpenAI 兼容 API 在您的本地服务器上运行,地址为 http://localhost:11434/v1/。OpenAI SDK 需要一个 API 密钥值,但本地 Ollama 会忽略它。
OpenRouter是否与OpenAI兼容?
是的。OpenRouter 的 OpenAI 兼容基础 URL 是 https://openrouter.ai/api/v1。
是否有免费的OpenAI兼容API?
本地服务器(如Ollama、LM Studio和vLLM)可以在您自己的硬件上免费运行。许多托管提供商也提供有限制的免费层。
Groq API 是否与 OpenAI 兼容?
是的。Groq OpenAI 兼容的基础 URL 是 https://api.groq.com/openai/v1。注意路径中额外的 /openai:使用纯 /v1 URL 是常见的设置错误。您更改基础 URL、API 密钥和模型名称,您的代码保持不变,除非您依赖 Groq 处理方式不同的功能。
相关文章
2026年最便宜的大模型API:每100万Token的实测价格
哪个大模型 API 最便宜?本文提供经过核实的 OpenAI、Claude、Gemini、DeepSeek、Qwen、Mistral 和 Groq 的价格,以及真实工作负载成本和隐藏费用。
AI智能体市场:2026年寻找、运行和销售AI智能体的10大最佳平台
什么是AI智能体市场,对10个顶级平台在试用成本和谁可以出售方面进行比较,并附上安全清单,以及如何在2026年上架您自己的智能体。
免费LLM API:2026年哪些提供商仍然免费(限制、密钥和注意事项)
2026年值得使用的每个免费LLM API,根据官方文档核实:免费层级对比积分、限制、数据条款、如何获取密钥和备用代码。
OpenRouter 替代方案:7 个大型语言模型网关在路由、定价和锁定方面的比较
OpenRouter替代方案对比:7个LLM网关的费用、路由、BYOK和自托管方案,包含迁移清单和2026年最新价格验证。








