OpenAI API compatible 是什么意思？

更新于 2026-10-23 · agentearth.cyou

简答：OpenAI API compatible 通常不是 OpenAI 官方 API，而是第三方服务、网关或本地模型服务，提供与 OpenAI 类似的鉴权方式、请求路径和 JSON 格式。简单文本对话有时只需更换 Base URL、API Key 和 model，但流式输出、工具调用、结构化输出、图片文件和错误格式仍需单独验证。

定义：OpenAI API compatible（OpenAI API 兼容）是指某个服务在接口地址、鉴权方式、请求字段或响应结构等方面，能够按照 OpenAI API 的一种或多种调用方式工作。

先看结论：兼容的是接口，不是“变成了 OpenAI”

可以把 API 兼容理解成“插头规格相近”：应用知道该向哪个路径发送请求、如何携带 API Key、如何组织 JSON，服务端也能返回应用预期的结构；但插头相同，不代表电器的功率、功能和性能完全相同。

OpenAI 官方文档把 Chat Completions 定义为根据消息列表生成模型响应的接口，并列出 /chat/completions 路径、model、messages 和流式响应等概念。新项目则可以进一步查看官方推荐的 Responses API，它使用 /responses 端点，并支持输入、输出、工具和状态等更完整的能力。具体可参考 Chat Completions API 参考 和 Responses API 参考。

因此，看到“OpenAI API compatible”时，不应直接理解为“这是 OpenAI 官方 API”“一定需要 OpenAI 账号”或“所有 OpenAI 功能都能用”。服务的实际身份、模型来源、计费方式、限速和功能范围，应以该服务自己的公开文档为准。

本站为第三方指南，非 OpenAI 官方，以其官网为准。

兼容范围可以分成五层

兼容程度必须结合具体端点和具体模型判断。即使一个服务能够处理 /chat/completions，也不能据此推断它支持 /responses、内置工具或相同的流式事件。OpenAI 官方参考文档分别列出了 Chat Completions 的创建方法和 Responses 的创建方法，二者路径与请求结构并不相同，可分别查看 Chat Completions 创建接口 与 Responses 接口。

新手配置检查表：四个字段分别填什么

关于是否带 /v1：不能只凭经验决定。若服务文档把 /v1 作为 API 根路径，就把它放在 Base URL 中；如果客户端会自动拼接版本路径，就不要重复添加。OpenAI 官方认证示例使用 https://api.openai.com/v1/models 和 https://api.openai.com/v1/chat/completions，同时说明 API Key 应通过 Bearer 认证发送，详见 OpenAI API 认证文档。

配置前可按这个顺序检查：先确认服务文档中的 Base URL，再确认模型列表中的 model ID，随后确认客户端最终请求路径，最后用最小文本请求验证。不要把完整 endpoint 粘贴到 Base URL 字段中，也不要把 API Key 写入前端代码、提交到 Git 仓库或直接打印到日志。

最小请求怎么验证：先测 Chat Completions

如果目标服务声称兼容 Chat Completions，可以先用一个只包含文本消息的最小请求。下面的示例不代表任意服务都使用同一个地址和模型名，BASE_URL、API_KEY、MODEL_ID 必须替换为目标服务文档中的值。

curl -i "$BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "user", "content": "请只回复：连接成功"}
    ],
    "stream": false
  }'

如果返回成功，至少说明该地址、鉴权、模型名和基础 JSON 结构能够完成一次调用；这仍不代表工具调用、结构化输出或流式解析也兼容。检查响应时，重点看 HTTP 状态码、响应是否为 JSON、文本内容位于哪个字段，以及是否返回 usage 信息。

如果使用 OpenAI Python SDK，官方库支持通过 base_url 或 OPENAI_BASE_URL 覆盖默认 API 地址，示例可参考 OpenAI Python SDK 文档：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
)

response = client.chat.completions.create(
    model=os.environ["OPENAI_MODEL"],
    messages=[
        {"role": "user", "content": "请只回复：连接成功"}
    ],
)

print(response.choices[0].message.content)

如果 SDK 报模型不存在、路径不存在或参数不支持，优先把 SDK 请求转换成可见的 HTTP 请求，分别核对 Base URL、endpoint、model 和请求体。Key 只验证“是否存在”和请求是否得到预期鉴权结果，不要把完整 Key 打印出来。

Chat Completions 和 Responses API 不是同一个端点

Chat Completions 通常围绕 messages 组织对话，调用路径是 /chat/completions；Responses API 使用 /responses，官方文档展示了 input、工具和响应对象等不同结构。OpenAI 当前文档建议新项目尝试 Responses，但第三方兼容服务可能只实现其中一种，或只实现其中一部分。

因此，“兼容 OpenAI API”必须追问三个问题：兼容哪个 API 家族、兼容哪些模型、兼容到什么功能层级。若客户端默认调用 Responses，而服务只提供 Chat Completions，需要在客户端中切换 API 类型或调整代码；反过来也一样。

常见报错与排查顺序

错误码只能帮助定位方向，不能单独证明故障原因。最稳妥的排查顺序是：确认 Base URL → 确认最终 endpoint → 确认 Key 读取成功 → 确认 model ID → 删除可选参数 → 关闭流式 → 再逐项开启高级功能。

哪些场景适合使用 OpenAI 兼容接口

• 适合：已有代码基于 OpenAI SDK 或 Chat Completions，希望用较小改动接入另一个模型服务、网关或本地推理服务。
• 适合：需要在多个模型提供方之间保留统一的基础调用层，并由应用自行管理模型 ID 和能力差异。
• 谨慎：依赖工具调用、结构化输出、图片、音频、文件、长上下文或严格流式协议的应用。
• 谨慎：对错误格式、用量统计、限速、并发和计费有严格要求的生产系统。
• 不应直接假设：兼容接口会自动提供 OpenAI 的全部模型、内置工具、账号权限或服务质量。

上线前至少用真实业务请求做一次契约测试：普通文本、长输入、流式输出、错误请求、工具调用和目标模型各测一遍，并保存不含密钥的请求摘要、HTTP 状态码和响应结构。这样才能把“宣传上的兼容”变成“你的应用实际可用”。

常见问题

OpenAI API compatible 是 OpenAI 官方 API 吗？

通常不是。它一般表示第三方服务采用了部分 OpenAI 风格的接口格式。是否使用 OpenAI 模型、是否需要 OpenAI 账号、Key 由谁签发，都要以实际服务文档为准。

是不是只改 Base URL 和 API Key 就能用？

简单文本请求有时可以，但不能保证。通常还要确认 model ID、是否需要 /v1、最终 endpoint、参数支持范围和响应格式。若原应用调用 Responses，而目标服务只支持 Chat Completions，还需要修改调用方式。

Base URL 应该填到哪一级，要不要带 /v1？

以目标服务文档和客户端拼接规则为准。Base URL 应是 API 根地址，不要填完整的 /chat/completions。如果文档给出的根地址是 https://api.openai.com/v1，就不要再额外拼接一次 /v1；如果客户端会自动补版本路径，则按客户端要求填写。

兼容接口能直接使用所有 OpenAI 参数吗？

不能保证。参数可能因模型、端点或兼容层而不同。遇到 unsupported_parameter 时，先删除非必需参数，再查目标服务的模型和端点说明。

如何判断流式输出是否真的兼容？

先用非流式请求确认基础调用，再开启 stream，观察返回是否为客户端能够解析的 SSE 或事件格式。能返回文本不等于流式事件、结束标记和 usage 字段完全一致。

使用兼容接口时 API Key 应该放在哪里？

服务端应用优先通过环境变量或密钥管理服务读取 Key，并以 Bearer 认证发送；不要把 Key 写进浏览器端代码、公开仓库或普通日志。OpenAI 官方认证文档也明确提醒 API Key 属于秘密信息。

常见问题

OpenAI API compatible 是 OpenAI 官方 API 吗？

通常不是。它一般表示第三方服务采用了部分 OpenAI 风格的接口格式，模型来源、账号要求和 Key 签发方需要以实际服务文档为准。

是不是只改 Base URL 和 API Key 就能用？

简单文本请求有时可以，但还要确认 model、/v1、endpoint、参数和响应格式。若目标服务不支持原应用使用的 API 类型，还需要修改调用代码。

Base URL 要不要带 /v1？

以服务文档和客户端拼接规则为准。Base URL 应是 API 根地址，不要填完整的 /chat/completions；如果根地址已经包含 /v1，就不要重复添加。

兼容接口能支持所有 OpenAI 参数吗？

不能保证。参数支持可能随模型和端点变化，遇到 unsupported_parameter 时应删除非必需参数，并查看目标服务的支持列表。

如何验证流式输出是否兼容？

先关闭 stream 验证普通响应，再开启流式请求，检查 SSE 或事件格式、结束标记和 usage 字段是否符合客户端解析逻辑。

相关阅读

• 返回 AgentEarth 首页查看更多 AI API 接入指南

参考资料

1. OpenAI API 认证文档
2. OpenAI Chat Completions API 参考
3. OpenAI Chat Completions 创建接口
4. OpenAI Responses API 参考
5. OpenAI Responses API CLI 参考
6. OpenAI Python SDK 官方仓库