大模型 API 格式的前世今生

OpenAI、Anthropic、Gemini 各搞一套 API 格式，OpenAI 自己还搞了两套。到底怎么回事？

我们打开各家大模型的 API 文档，会发现一个让人头疼的事实：每家的请求格式都不一样。

OpenAI 用 messages，Anthropic 也用 messages 但结构不同，Gemini 用 contents。更离谱的是，OpenAI 自己还搞了两套格式——仿佛一套不够乱似的。

如果我们曾经把 OpenAI 的请求体直接丢给 Anthropic，然后对着 400 错误发呆，这篇文章就是写给我们自己的。一起来理清楚：这些格式是怎么来的，有什么区别，国内开发者该跟哪个。

起点：OpenAI Chat Completions API

2023 年 3 月，OpenAI 发布了 Chat Completions API，这是一切的起点。

核心结构很简单：

{
    "model": "gpt-4o",
    "messages": [
        {"role": "system", "content": "你是一个有用的助手。"},
        {"role": "user", "content": "你好"}
    ]
}

关键设计：

• 用 messages 数组表示对话历史
• 每条消息有 role（system / user / assistant）和 content
• 模型选择通过 model 字段指定
• 返回结果在 choices[0].message.content 里

这个格式因为 ChatGPT 的爆火迅速成为事实标准——就像 USB 接口一样，不一定是最优设计，但大家都用它。后来加入 Function Calling 时，在 messages 里新增了 tool 角色和 tools 参数，但整体骨架没变。

用 Java 调长这样：

String body = """
        {
            "model": "gpt-4o",
            "messages": [
                {"role": "system", "content": "你是一个有用的助手。"},
                {"role": "user", "content": "你好"}
            ]
        }
        """;

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.openai.com/v1/chat/completions"))
        .header("Authorization", "Bearer YOUR_KEY")
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();

Anthropic Messages API：另起炉灶

2024 年 3 月，Anthropic 发布 Claude 3 系列时推出了 Messages API。它没有跟 OpenAI 的格式，而是自己设计了一套：

{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "你是一个有用的助手。",
    "messages": [
        {"role": "user", "content": "你好"}
    ]
}

和 OpenAI 的关键区别：

对比项	OpenAI	Anthropic
system prompt	放在 messages 数组里，role 为 “system”	独立的 system 字段
max_tokens	可选参数	必填参数
认证方式	Authorization: Bearer sk-xxx	x-api-key: sk-ant-xxx
返回结构	choices[0].message.content	content[0].text
content 格式	字符串或数组	始终是数组（支持多模态）

最大的设计差异是 system 独立出来了。Anthropic 认为 system prompt 不是对话的一部分，而是对模型行为的全局指令，不应该和用户消息混在一起。这个设计后来被证明是更好的选择。

Java 代码：

String body = """
        {
            "model": "claude-sonnet-4-20250514",
            "max_tokens": 1024,
            "system": "你是一个有用的助手。",
            "messages": [
                {"role": "user", "content": "你好"}
            ]
        }
        """;

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.anthropic.com/v1/messages"))
        .header("x-api-key", "YOUR_KEY")
        .header("anthropic-version", "2023-06-01")
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();

OpenAI Responses API：自己革自己的命

2025 年 3 月，OpenAI 推出了 Responses API，定位为 Chat Completions 的下一代替代：

{
    "model": "gpt-4o",
    "instructions": "你是一个有用的助手。",
    "input": "你好"
}

变化很大：

对比项	Chat Completions	Responses API
对话历史	messages 数组	input（字符串或数组）
system prompt	messages 里的 system 角色	独立的 instructions 字段
返回结构	choices[0].message	output[0].content[0].text
工具调用	tools + tool_choice	内置 web_search、file_search 等
上下文管理	手动拼接历史	previous_response_id 自动串联

注意到了吗？instructions 独立出来了——和 Anthropic 的 system 一样的思路。OpenAI 等于承认了早期设计的不足。

previous_response_id 是个亮点：不用再手动维护对话历史数组，传一个 ID 就能接上之前的对话。对 Agent 场景来说，这比手动拼 messages 方便太多了。

Google Gemini API：又一套方言

Google 的 Gemini API 走了完全不同的路：

{
    "system_instruction": {
        "parts": [{"text": "你是一个有用的助手。"}]
    },
    "contents": [
        {
            "role": "user",
            "parts": [{"text": "你好"}]
        }
    ]
}

Gemini 的特点：

• 用 contents 而不是 messages
• 每条消息的内容放在 parts 数组里（而不是直接用 content 字符串）
• system prompt 用 system_instruction，也是独立的
• 角色只有 user 和 model（不是 assistant）

这个 parts 设计其实是为多模态准备的——文本、图片、音频都是不同的 part，可以自由组合。但对于纯文本场景，确实显得啰嗦。

国内平台：跟 OpenAI 就对了

好消息是，国内主流大模型平台几乎都兼容 OpenAI Chat Completions 格式：

平台	兼容 OpenAI 格式	端点
阿里云百炼（通义千问）	✅	https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
DeepSeek	✅	https://api.deepseek.com/v1/chat/completions
智谱 AI（GLM）	✅	https://open.bigmodel.cn/api/paas/v4/chat/completions
月之暗面（Kimi）	✅	https://api.moonshot.cn/v1/chat/completions

也就是说，学会 OpenAI 的格式，换个 URL 和 API Key 就能调国内的模型。这是 OpenAI 格式成为事实标准的最大好处。

四种格式对比总结

特性	OpenAI Chat	Anthropic Messages	OpenAI Responses	Gemini
发布时间	2023.03	2024.03	2025.03	2024.02
对话字段	messages	messages	input	contents
system 位置	messages 内	独立 system	独立 instructions	独立 system_instruction
内容格式	string/array	array	string/array	parts array
国内兼容	✅ 广泛	❌	❌	❌
适合场景	通用	Claude 模型	OpenAI 新功能	Gemini 模型

该学哪个格式

如果我们是刚入门的开发者，建议：

1. 先学 OpenAI Chat Completions 格式 — 它是事实标准，国内平台都兼容，学一次到处用
2. 了解 Anthropic Messages API — Claude 系列模型能力很强，直接调用时需要用它的格式，而且它的 system 独立设计确实更优雅
3. Responses API 和 Gemini API 先知道有这回事就行，等需要时再翻文档不迟

做 Agent 开发的话，Chat Completions 格式的 Function Calling 是基础中的基础，后面的系列文章会详细讲。

一个有意思的趋势

我们会发现，后出的格式都在把 system 从对话历史里独立出来（Anthropic 的 system、OpenAI Responses 的 instructions、Gemini 的 systemInstruction）。

这不是巧合。实践证明，system prompt 和对话消息混在一起容易出问题——比如多轮对话时 system 被"挤"到很远的位置，模型可能会"忘记"它。独立出来在语义上更清晰，实现上也更好优化。

Chat Completions 格式虽然是事实标准，但它把 system 放在 messages 里的设计，其实是早期的历史包袱。就像 JavaScript 里的 var，能用，但新项目里我们不会再写它了。

各家官方文档

最后附上各家 API 的官方文档入口，建议收藏备查：

平台	文档地址
OpenAI Chat Completions	platform.openai.com/docs/api-reference/chat
OpenAI Responses	platform.openai.com/docs/api-reference/responses
Anthropic Messages	docs.anthropic.com/en/api/messages
Google Gemini	ai.google.dev/api
阿里云百炼	help.aliyun.com/zh/model-studio
DeepSeek	api-docs.deepseek.com
智谱 AI	open.bigmodel.cn/dev/api
月之暗面	platform.moonshot.cn/docs/api

---

下一篇，我们动手用百炼平台跑一次完整的 API 调用，把每个参数拆开看清楚。觉得有用的话点个收藏，后续系列持续更新。

本文中的 API 格式和端点信息基于 2026 年 4 月各平台公开文档整理，如有变动请以官方最新文档为准。