技术博客

大模型 API 格式的前世今生

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

发布时间

2026年4月3日

阅读信息

约 15 分钟

主题标签

大模型 API / OpenAI / Anthropic

我们打开各家大模型的 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：相似但不同

Anthropic 的 Claude 系列用的是 Messages API。乍一看和 OpenAI 很像，但细节上有明显差异——就像两个长得像的双胞胎，穿的衣服完全不一样：

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

和 OpenAI 的关键区别：

差异点	OpenAI	Anthropic
system 消息	放在 messages 数组里	独立的 `system` 字段
max_tokens	可选	必填
返回结构	`choices[0].message.content`	`content[0].text`
认证方式	`Authorization: Bearer`	`x-api-key`
端点	`/v1/chat/completions`	`/v1/messages`

Anthropic 把 system 提出来单独放，理由是 system prompt 的语义和对话消息不同，不应该混在一起。这个设计确实更清晰，但也意味着我们不能直接把 OpenAI 的请求体复制粘贴过来——别问我怎么知道的。

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();

注意多了一个 anthropic-version 头，这是 Anthropic 的 API 版本控制机制。

Google Gemini API：另起炉灶

Google 的 Gemini API 走了一条完全不同的路。毕竟是 Google，怎么能用别人定义的格式呢：

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

最大的不同：

不叫 messages，叫 contents
消息内容不是 content 字符串，而是 parts 数组
system 指令用 systemInstruction
端点格式是 /v1beta/models/{model}:generateContent

parts 数组的设计是为了原生支持多模态——文本、图片、音频可以放在同一条消息的不同 part 里。设计思路没问题，但对于纯文本场景来说，多了一层嵌套显得啰嗦。就好比我们只想发条短信，结果要先打开一个多媒体编辑器。

Java 调用：

String body = """
        {
            "contents": [
                {
                    "role": "user",
                    "parts": [{"text": "你好"}]
                }
            ],
            "systemInstruction": {
                "parts": [{"text": "你是一个有用的助手。"}]
            }
        }
        """;

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(
            "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=YOUR_KEY"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .build();

OpenAI 的第二套：Responses API

2025 年，OpenAI 推出了 Responses API，这是他们自己的”第二套格式”。你没看错，OpenAI 觉得自己定义的标准不够好，于是又定义了一个新的：

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

和 Chat Completions 的对比：

差异点	Chat Completions	Responses API
对话历史	`messages` 数组	`input`（可以是字符串或数组）
system 消息	在 messages 里	独立的 `instructions` 字段
工具调用	`tools` + `tool_choice`	`tools`（内置了更多工具类型）
上下文管理	自己维护 messages	可用 `previous_response_id` 自动串联
端点	`/v1/chat/completions`	`/v1/responses`

Responses API 的设计明显借鉴了 Anthropic 的思路（system 独立出来），同时加入了对话状态管理（previous_response_id），不用自己拼 messages 了。看来 OpenAI 也承认了：把 system 塞在 messages 里，确实不是个好主意。

它还内置了 web_search、file_search、code_interpreter 等工具，更偏向 Agent 场景。

但目前 Responses API 还比较新，生态兼容性不如 Chat Completions。国内平台也没有跟进兼容这套格式，所以短期内它更像是 OpenAI 自己的”方言”。

四种格式一览

把核心差异放在一起看：

	OpenAI Chat	OpenAI Responses	Anthropic	Gemini
对话字段	`messages`	`input`	`messages`	`contents`
system	在 messages 里	`instructions`	`system`	`systemInstruction`
消息内容	`content`	`content`	`content`	`parts[].text`
认证	Bearer token	Bearer token	x-api-key	URL 参数或 Bearer
端点	`/chat/completions`	`/responses`	`/messages`	`/:generateContent`

国内平台：OpenAI 兼容格式一统天下

看完上面四种格式我们可能头大了。好消息是：国内主流平台几乎都选择了兼容 OpenAI Chat Completions 格式。大家心照不宣地达成了共识——既然打不过，就加入。

平台	兼容端点	模型示例	文档
阿里云百炼	`dashscope.aliyuncs.com/compatible-mode/v1`	qwen-plus	文档
DeepSeek	`api.deepseek.com/v1`	deepseek-chat	文档
智谱 AI	`open.bigmodel.cn/api/paas/v4`	glm-4-plus	文档
月之暗面	`api.moonshot.cn/v1`	moonshot-v1-8k	文档

这意味着我们用 OpenAI 的 Chat Completions 格式写的代码，换个地址和模型名就能调国内的模型。

比如从百炼切到 DeepSeek：

// 百炼
.uri(URI.create("https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"))
// model: "qwen-plus"

// DeepSeek
.uri(URI.create("https://api.deepseek.com/v1/chat/completions"))
// model: "deepseek-chat"

代码结构一行不用改。

该学哪个格式

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

先学 OpenAI Chat Completions 格式 — 它是事实标准，国内平台都兼容，学一次到处用
了解 Anthropic Messages API — Claude 系列模型能力很强，直接调用时需要用它的格式，而且它的 system 独立设计确实更优雅
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

关注更新

如果这篇文章对你有帮助，欢迎关注公众号「粒方Lab」。

下一篇，我们动手用百炼平台跑一次完整的 API 调用，把每个参数拆开看清楚。

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

大模型 APIOpenAIAnthropicGeminiJava