聊聊主流 AI API 格式：从 OpenAI、Claude 到 Gemini，谁更好用？

做 AI 应用这一年多，我调过市面上几乎所有主流大模型的 API。一个很深的感受是：API 格式的混乱程度，远比想象中严重。虽然现在张口闭口“兼容 OpenAI”，但真上手 Claude 和 Gemini 的时候，该踩的坑一个都不会少。

这篇文章不教你怎么写代码，而是帮你把这些格式的来龙去脉、设计差异、以及为什么大家都抄 OpenAI 这件事彻底聊清楚。看完你至少能明白：什么时候无脑上 OpenAI 格式，什么时候值得老老实实看 Claude 或 Gemini 的原生文档。

1. OpenAI API（Chat Completions）—— 事实标准

最早大规模对外开放 LLM API 的，确实是 OpenAI。从 2020 年的 davinci 补全接口，到 2021‑2022 年前后定型的 Chat Completions，这个格式基本奠定了今天的“标准”长相。

核心接口

/v1/chat/completions（你现在每天调的那个）
/v1/completions（旧版纯文本补全，已经边缘化，但不少自建模型还在用）

请求结构（看懂这个你就懂了 80% 的兼容 API）

{
  "model": "gpt-4",
  "messages": [
    {"role": "system", "content": "你是一个幽默的导游"},
    {"role": "user", "content": "介绍一下自由女神像"},
    {"role": "assistant", "content": "她是个很高的女士…"},
    {"role": "user", "content": "多高？"}
  ],
  "temperature": 0.7,
  "max_tokens": 500,
  "tools": [...]   // 函数调用可选
}

响应结构

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "从地面到火炬顶端是 93 米…"
    },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 50, "completion_tokens": 20 }
}

特点与优势

极低的接入门槛：一个 messages 数组搞定所有对话历史，role 只有三种，小学生都能看懂。
SDK 最成熟：Python、Node、Java 官方库稳如老狗，社区还有无数封装。
工具调用（function calling） 虽然被后来者（Claude、Gemini）优化得更优雅，但 OpenAI 的原始设计足够简单有效。

为什么几乎所有后发模型都“兼容 OpenAI”？

不是因为他们爱 OpenAI，而是因为 开发者已经被驯化了。

你想想：2023 年初，市面上的 LLM API 屈指可数，大量的开源库（LangChain、LlamaIndex）、IDE 插件（Continue、Cline）、本地推理框架（Ollama、vLLM）都是直接写死 OpenAI 的请求格式。一个新模型出来，如果它说“兼容 OpenAI API”，那意味着——开发者一行代码都不用改，只换 base_url 和 api_key 就能跑起来。

这对商业公司来说太香了。不需要自己维护 SDK，不需要写接入文档，甚至可以直接蹭 OpenAI 的生态。所以你会看到：DeepSeek、Groq、Together.ai、零一万物、百川、通义、智谱…… 全部支持 /v1/chat/completions 格式。

当然，兼容不等于 100% 一致。有的不支持 tools，有的对 max_tokens 解释不同（有的当 max_completion_tokens 处理），但核心的 messages 结构几乎没敢动过。

那 OpenAI 自己有没有别的格式？

大纲里提到了“OpenAI Response API”，这里澄清一下：OpenAI 官方文档里并没有一个叫 Response API 的独立接口。旧版 /v1/completions 返回的就是一个 response 对象，有人随口叫它 Response API，但现在已经不推荐使用了。Chat Completions 才是唯一正道。

2. Claude API（Anthropic Messages API）

Anthropic 在 2023 年底推出 Claude 2 的时候，并没有选择兼容 OpenAI。他们自己设计了一套 Messages API，某种程度上比 OpenAI 更“干净”。

核心接口

/v1/messages

请求结构（注意和 OpenAI 的明显差异）

{
  "model": "claude-3-opus-20240229",
  "system": "你是一个幽默的导游",      // system 单独拎出来，不在 messages 里
  "messages": [
    {"role": "user", "content": "介绍一下自由女神像"},
    {"role": "assistant", "content": "她是个很高的女士…"},
    {"role": "user", "content": "多高？"}
  ],
  "max_tokens": 1024,        // 必填，没有默认值
  "temperature": 0.7,
  "stop_sequences": ["\n\nHuman:"]
}

响应结构

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [{
    "type": "text",
    "text": "从地面到火炬顶端是 93 米…"
  }],
  "stop_reason": "end_turn",   // 可能是 end_turn / max_tokens / stop_sequence
  "usage": { "input_tokens": 50, "output_tokens": 20 }
}

特点与优势

system 字段外置：逻辑上更清晰，不用在 messages 里混一个 role: system。
强制 max_tokens：避免你忘了设导致响应被截断（OpenAI 是有默认值的，但经常不是你想要的）。
stop_reason 非常明确：你一眼就知道是因为自然结束还是长度限制，对工程化很有帮助。
工具调用设计更显式：需要单独一个 tools 字段，且响应的 content 里会返回 tool_use 的 block。

缺点（对开发者而言）

不兼容 OpenAI 格式，意味着你不能直接用 LangChain 的 OpenAI 类去连 Claude 的端点，除非自己写 adapter。
长上下文是优势（200K tokens），但同时也意味着你得多花钱。

典型场景

长文档分析（合同、财报、技术手册）
需要稳定控制输出格式的 RAG 应用（Claude 对 XML 风格的 prompt 响应最好）

3. Google Gemini API

Google 起步最晚，但野心最大。Gemini API 的设计完全不是“跟着 OpenAI 走”，而是原生多模态优先。

核心接口

/v1/models/{model}:generateContent（非流式）
/v1/models/{model}:streamGenerateContent（流式）

请求结构（第一次看会觉得别扭）

{
  "contents": [
    {
      "role": "user",          // 只能是 user 或 model
      "parts": [
        {"text": "这张图里有什么？"},
        {"inline_data": {"mime_type": "image/jpeg", "data": "base64..."}}
      ]
    }
  ],
  "systemInstruction": {
    "parts": [{"text": "你是一个幽默的导游"}]
  },
  "generationConfig": {
    "temperature": 0.7,
    "maxOutputTokens": 500,
    "topP": 0.9
  },
  "safetySettings": [...]     // 细粒度安全过滤
}

响应结构

{
  "candidates": [{
    "content": {
      "parts": [{"text": "图片里有一座绿色的自由女神像？"}],
      "role": "model"
    },
    "finishReason": "STOP",
    "safetyRatings": [...]
  }],
  "usageMetadata": { ... }
}

特点与优势

多模态是真的原生：文本、图片、视频、音频都通过 parts 数组传入，不需要像 OpenAI 那样用特殊格式的 content 字符串。
安全过滤器非常细：可以按 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_DANGEROUS_CONTENT 等分别设置阈值，适合企业合规场景。
systemInstruction 相当于 Claude 的 system 字段，也是外置的。
不同变体（Flash、Pro、Ultra）共用同一套 API，切换模型不用改代码结构。

缺点

学习曲线略陡：contents + parts + generationConfig 嵌套层级多。
生态工具支持不如 OpenAI 广泛，LangChain 虽然有 Gemini 集成，但稳定性和细节覆盖度稍差。

典型场景

图像识别 + 文本生成（比如识图后写产品描述）
视频内容摘要（Gemini 1.5 Pro 可处理数小时视频）
需要 Google 搜索增强的实时信息场景

4. 格式对比总结（一张表看懂）

维度	OpenAI 风格	Claude Messages API	Gemini API
核心字段	`messages`	`messages` + `system` 分开	`contents` + `systemInstruction`
System 角色	一个 `role: system` 的消息	顶级 `system` 字段	顶级 `systemInstruction`
多模态支持	有限（需将图片转成特殊 content）	有限（仅支持图片）	原生极强（图片/视频/音频）
必填安全参数	无	无（但有隐式安全过滤）	可选但细粒度
学习曲线	低	中	中高
第三方生态广度	极高（几乎所有工具原生支持）	中（需 adapter）	中（Google 自家工具链强）
典型 `finish_reason`	`stop` / `length`	`end_turn` / `max_tokens`	`STOP` / `MAX_TOKENS`

5. 实践建议（给正在选型的你）

什么时候闭眼选 OpenAI 格式？

你需要在多个模型之间频繁切换（比如今天用 DeepSeek，明天用 Groq）
你要接入 LangChain、Dify、Continue、Cline 等现有生态
你的团队规模小，不想维护多套 adapter
你的核心场景是纯文本对话、函数调用

什么时候值得用 Claude 原生格式？

你确定长期只用 Claude（长上下文带来的 ROI 明显）
你需要非常清晰的 stop_reason 来做精细工程控制
你对 Anthropic 的“可解释性”和安全性有硬性要求

什么时候上 Gemini 原生格式？

多模态不是你偶尔的 feature，而是核心卖点（比如每天处理数万张图片）
你需要 Google 级别的安全审核策略
你已经深度使用 Google Cloud 生态（BigQuery、Vertex AI 等）

代码层面的最佳实践（我踩坑后总结的）

不要直接在业务代码里写死某种 API 格式。做一个薄薄的适配器层：

# 内部统一的数据结构
class MyChatMessage:
    role: str   # user / assistant / system
    content: str

# 三个转换函数
def to_openai(messages) -> dict: ...
def to_claude(messages, system) -> dict: ...
def to_gemini(messages, system) -> dict: ...

这样你可以先适配 OpenAI，跑通业务，未来要切 Claude 或 Gemini 时，只需要替换转换函数和 base_url。

6. 格式示例（直接丢 curl 里就能跑）

OpenAI 风格（兼容 DeepSeek / Groq / Ollama）

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Claude 原生

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-haiku-20240307",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Gemini 原生

curl "https://generativelanguage.googleapis.com/v1/models/gemini-1.5-flash:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts":[{"text": "Hello"}]}]
  }'

尾巴

没有所谓“最好”的 API 格式。OpenAI 赢在先行者红利和生态，Claude 赢在工程细节和长上下文，Gemini 赢在多模态和 Google 背后的数据能力。

但有一个趋势很明显：OpenAI 格式已经成了 LLM API 界的 UTF-8——它不是最完美的，但大家都在用它。如果你只打算深入一家，安心学它的原生格式；如果你要做通用工具，请无条件拥抱 OpenAI 格式。

剩下的，交给你的业务场景去投票吧。

打赏赞