scriptRun Beta

OpenAI兼容API:它是什么、谁支持它以及如何安全切换

AnnaAnna
17 十一月 2026
商业
人工智能工作流程自动化
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 指向不同的服务器:

  1. 基础 URL: 供应商的端点,例如 Gemini 的 https://generativelanguage.googleapis.com/v1beta/openai/。

  2. API 密钥: 供应商的密钥,而不是你的 OpenAI 密钥。

  3. 模型名称: 该供应商的模型 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参考 APIhttps://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 匹配,但详细错误消息不匹配,某些速率限制标头的名称不同。

来源:Anthropic,OpenAI SDK 兼容性。

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 并不总是排除某个供应商。它告诉你代码的哪一部分需要变通方法,或哪些请求应该保留在另一个模型上。

迁移检查列表:在不破坏生产的情况下切换

  1. 列出你使用的内容。 端点、参数、工具、JSON 模式、流式处理、图像和文件。

  2. 检查供应商的兼容性页面 了解每一项,特别是被静默忽略的字段。

  3. 运行冒烟测试 使用你真实的提示和模型。

  4. 将配置移到环境变量中: 基础 URL、密钥和模型。切换回去只是配置更改,不需要部署。

  5. 比较真实请求样本的输出: 质量、延迟和每 1,000 个请求的成本。

  6. 逐步推出。 从少量流量或内部功能开始。

  7. 监视错误和速率限制, 并在前几周将旧供应商保留为备用方案。

使用 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 密钥 并使用你已有的代码尝试。


有帮助吗?
分享这篇文章!

几分钟内构建 AI workflow

创建自动化流程,连接 API,并在一个平台上访问 50 多种 AI 模型。

可视化 workflow 构建器
兼容 OpenAI 的 API
workflow 市场与模板
免费开始使用,套餐低至 $5

关于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的实测价格
商业 20 十一月 2026

2026年最便宜的大模型API:每100万Token的实测价格

哪个大模型 API 最便宜?本文提供经过核实的 OpenAI、Claude、Gemini、DeepSeek、Qwen、Mistral 和 Groq 的价格,以及真实工作负载成本和隐藏费用。

1734
AnnaAnna
AI市场人工智能工作流程自动化
AI 智能体市场:10 大最佳平台对比(2026)
商业 19 十一月 2026

AI智能体市场:2026年寻找、运行和销售AI智能体的10大最佳平台

什么是AI智能体市场,对10个顶级平台在试用成本和谁可以出售方面进行比较,并附上安全清单,以及如何在2026年上架您自己的智能体。

1886
AnnaAnna
人工智能工作流程自动化
免费LLM API:2026年供应商、限制和真实陷阱
商业 18 十一月 2026

免费LLM API:2026年哪些提供商仍然免费(限制、密钥和注意事项)

2026年值得使用的每个免费LLM API,根据官方文档核实:免费层级对比积分、限制、数据条款、如何获取密钥和备用代码。

1905
AnnaAnna
人工智能工作流程自动化
OpenRouter替代品:7个LLM路由网关
商业 16 十一月 2026

OpenRouter 替代方案:7 个大型语言模型网关在路由、定价和锁定方面的比较

OpenRouter替代方案对比:7个LLM网关的费用、路由、BYOK和自托管方案,包含迁移清单和2026年最新价格验证。

1560
AnnaAnna
© 2024-2026 PIXEL LORIS IT SERVICES L.L.C. All rights reserved.