什么是 OpenAI 兼容 API：兼容了什么、哪里不一样、怎么切换

简短回答

OpenAI 兼容 API，指的是接受和 OpenAI API 一样的请求、按一样的格式返回结果的 HTTP API：路径相同（/v1/chat/completions、/v1/models，很多还有 /v1/responses），JSON 字段相同，用同样的 Authorization: Bearer 请求头传 Key。因此 OpenAI 官方 SDK 和大量基于它的工具，只要改两样东西就能接上：base URL 和 API Key。「兼容」说的是请求格式，不是背后的模型；每家服务只支持 OpenAI 功能的一部分，你依赖的功能要自己测一遍。

本文由 APIVAI 发布。APIVAI 是一个兼容 OpenAI 格式的 Claude 和 GPT 网关，示例用的是它的地址；换成任何兼容服务，步骤都一样。

「兼容」具体指什么

大多数服务照搬的是 OpenAI Chat Completions API 的核心部分：

部分	兼容服务接受或返回的内容
`POST /v1/chat/completions`	`model` 填模型 ID，`messages` 是由 `{"role": ..., "content": ...}` 组成的数组
响应	`choices[0].message.content`、`finish_reason`，以及 `usage` 对象（`prompt_tokens`、`completion_tokens`、`total_tokens`）
流式输出	`"stream": true` 时以 SSE 返回，每段文字一个 `data: {...}`，最后是 `data: [DONE]`
工具调用	`tools` 里用 JSON Schema 写 `parameters`；模型返回 `tool_calls`，你把结果作为 `role: "tool"` 的消息发回去
`GET /v1/models`	你的 Key 能用的模型 ID 列表
鉴权	`Authorization: Bearer <Key>`
错误	`{"error": {"message": ..., "type": ..., "code": ...}}` 格式的 JSON

较新的服务还实现了 POST /v1/responses，也就是 OpenAI 较新的 Responses API，有些工具（比如 Codex CLI）用它代替 Chat Completions。/v1/embeddings、图片、音频、文件这些接口，提供的服务要少得多。

各家哪里不一样：检查清单

兼容从来都不是百分之百。正式切换流量之前，逐项确认：

模型 ID：每家服务的模型命名都不一样，以 GET /v1/models 返回的为准，不要照搬 OpenAI 的名字。
被忽略的参数：不支持的字段经常被直接丢掉、不报错，常见的有 response_format、seed、logprobs、n > 1、presence_penalty，以及工具上的 strict。请求看起来「成功了」，实际做的事比你以为的少。
参数范围：有的模型会拒绝 OpenAI 能接受的值（比如 temperature 大于 1，或者同时设置 temperature 和 top_p）。
对话以外的接口：嵌入、图片、音频、文件、batch、微调经常没有。
流式输出的用量：流式响应里的 token 统计可能要加 "stream_options": {"include_usage": true} 才返回，也可能根本不返回。
错误和限流：错误 JSON 的结构一般一致，但状态码、报错文字和限流请求头（x-ratelimit-*、retry-after）各不相同。
工具调用和图片：大多数大模型都支持，但并行调用、强制 tool_choice、图片输入要在你实际要用的那个模型上测。

谁提供 OpenAI 兼容 API

几个文档齐全的例子：

服务	Base URL	说明
Ollama（本地）	`http://localhost:11434/v1`	Chat Completions、Completions、模型列表、嵌入，以及无状态的 Responses 接口；Key 必须填但不校验
vLLM（自部署）	`http://localhost:8000/v1`	用 `vllm serve <模型>` 启动；提供 Chat Completions、Completions、Responses、嵌入和模型列表
LM Studio（本地）	`http://localhost:1234/v1`	模型列表、Chat Completions、Completions、Responses 和嵌入
Anthropic	`https://api.anthropic.com/v1/`	Anthropic 说明这一层主要用于测试和对比模型，不算长期的生产方案；提示缓存和部分字段只有原生 API 才有
Google Gemini	`https://generativelanguage.googleapis.com/v1beta/openai/`	Google 标注为测试版
API 网关	网关自己的地址	把多家模型放在同一个 Key、同一种格式后面；APIVAI 就是其中之一，提供 Claude 和 GPT（另见 APIVAI 与 OpenRouter 对比）

留意 base URL：大多数以 /v1 结尾，Gemini 的不是。一律以服务方文档里写的为准。

怎么把应用切到另一个兼容服务

OpenAI 官方 SDK 会读取两个环境变量，所以很多应用不改代码就能切换：

export OPENAI_BASE_URL="https://api.apivai.com/v1"
export OPENAI_API_KEY="your-key"

也可以在代码里写。Python：

from openai import OpenAI

client = OpenAI(base_url="https://api.apivai.com/v1", api_key="your-key")
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(resp.choices[0].message.content)

Node.js：

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.apivai.com/v1", apiKey: "your-key" });
const resp = await client.chat.completions.create({
  model: "gpt-6-luna",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(resp.choices[0].message.content);

改应用之前先用 curl 测通：

curl https://api.apivai.com/v1/models -H "Authorization: Bearer your-key"

/v1 规则：SDK 会在 base URL 后面拼上 /chat/completions，所以 base URL 本身要带上版本路径（.../v1）。报 404 几乎都是 /v1 漏了或者重复了。各个工具拼接的内容不一样，以对应工具的教程为准。

支持自定义 OpenAI 兼容地址的工具

大多数 AI 编程和聊天工具都有「自定义 OpenAI 兼容」或「OpenAI base URL」设置。分步教程：

编程 Agent 和编辑器：Cline、Roo Code、Kilo Code、Continue、Cursor、Zed、Aider、OpenCode、Goose、Open Interpreter，以及 Codex CLI（见 Claude Code 配置教程）
聊天客户端：Cherry Studio、Chatbox、LobeChat、Open WebUI
自动化：Dify、n8n

用 OpenAI 格式调用 Claude

Claude 自己的 API 是另一种格式（/v1/messages、x-api-key、顶层的 system 字段）。要在 OpenAI 格式的工具里用 Claude，中间需要有一层做转换：可以用上面提到的 Anthropic 官方兼容层，也可以用 APIVAI 这样的网关——它在 https://api.apivai.com/v1 接受 OpenAI 格式的请求，模型 ID 填 Claude 的即可。本身就支持 Anthropic 格式的工具（比如 Claude Code）可以直接用 https://api.apivai.com，见 Claude Code 配置教程和 API 文档。

常见问题

「兼容 OpenAI」是不是 OpenAI 的功能都能用？

不是。兼容的是核心的请求和响应格式，每家只支持其中一部分：对话和流式输出几乎都有，工具调用和图片大多数大模型支持，嵌入、音频、文件和 batch 就少得多。不支持的字段经常被悄悄忽略，你依赖的功能一定要实测。

要不要改代码？

通常只改 base URL、Key 和模型 ID。如果代码用了 OpenAI 独有的功能（比如用 response_format 做结构化输出，或者 Assistants API），要先确认新服务是否支持。

同一套代码能不能连本地模型？

可以。Ollama、vLLM 和 LM Studio 都能起一个 OpenAI 兼容的服务，同样的 SDK 代码把 base_url 设成 http://localhost:11434/v1、http://localhost:8000/v1 或 http://localhost:1234/v1 就行。模型 ID 和支持的功能随服务和模型而变。

base URL 要不要带 /v1？

大多数服务要带：SDK 会拼上 /chat/completions，所以 base URL 要以版本路径结尾。也有服务路径不一样（Gemini 是 /v1beta/openai/），以服务方文档为准。

怎么知道一个服务支持哪些模型？

用你的 Key 调用 GET /v1/models，返回里的 ID 就是 model 要填的值。价格和上下文长度看服务方的价格页；APIVAI 的见模型页。