Chat Completions 和 Messages API 区别

先说结论:一个事实标准,一个独立方言

Chat completions(POST /v1/chat/completions)是几乎所有工具都在说的协议:一个无状态的 messages 数组进去,一个 choices 数组出来。OpenAI 2023 年发布了它,后来成了行业的通用语,几乎每一家厂商、每一个中转网关都实现了它,这也是"OpenAI 兼容"这个说法在实践里的真实含义。 Messages(POST /v1/messages)是 Anthropic 自己的原生协议:精神上和 chat completions 相似,但一些承重的细节不一样——max_tokens 是必填项,system 是顶层字段而不是一个角色,内容是类型化的 block,还有自己的一套流式事件词汇。Claude 原生的工具链说的是这套协议。 OpenAI 另外还有一个更新的 Responses API(POST /v1/responses),定位是 chat completions 的后继者,加了服务端会话状态和内置工具。这不是本页要展开对比的重点:kkaiapi 目前提供的是 /v1/chat/completions 和 /v1/messages 这两种无状态协议,Responses 不在当前文档记录的接口范围内,需要这个协议的工具应当继续对着 OpenAI 官方,或者留意 kkaiapi 文档后续是否加上支持。

两种协议逐项对照

下表压缩了真正会改动代码的差异,以 2026 年 7 月两家厂商现行文档为准核实。

差异落到代码里意味着什么

这两种无状态协议看起来相似,真正移植的时候才发现不一样。Anthropic 在每次请求上要求 max_tokens,OpenAI 这边有默认值。Anthropic 把 system 提示词从 messages 数组里拎出来,放进一个顶层字段,还强制 user/assistant 严格交替。工具调用流程在结构上也不一样:chat completions 在 assistant 消息上返回 tool_calls,结果作为 role 为 tool 的消息传回去;Messages 把 tool_use block 嵌进 assistant 的 content,结果作为 tool_result block 放进下一条 user 消息里。流式解析器在两者之间也不能复用:一个吐 delta 分块,另一个吐一套带名字的事件。

# 1) Chat completions:无状态,可移植
client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "system", "content": "回答要简洁。"},
              {"role": "user", "content": "总结这份文件。"}])

# 2) Messages:Anthropic 方言
anthropic_client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,                # 必填
    system="回答要简洁。",           # 顶层字段,不是一个角色
    messages=[{"role": "user", "content": "总结这份文件。"}])

kk 这边:两种协议都能打全部目录模型

kkaiapi 是把两种协议都实现了的中转:/v1/chat/completions 接受 OpenAI 形状的请求,对目录里任意模型都能用;/v1/messages 接受 Anthropic 形状的请求,同样对目录里任意模型都能用。这不只是理论上的双协议支持——Claude Code 说的就是 Messages 协议,而 kkaiapi 后端对 DeepSeek、智谱 GLM、月之暗面 Kimi、MiniMax、通义 Qwen 这些国产渠道都实现了协议转换层:收到 Messages 格式的请求后翻译给对应上游,拿到响应再翻译回 Messages 格式,这一点在 Claude Code 换国产模型跑法那篇里已经核实过,是网关 Go 后端的真实能力,不是理论描述。 换句话说,选哪种协议不再等同于选哪家厂商。一个 Claude 原生的 Agent 工具经 /v1/messages 打过来,能路由到 GLM 或 DeepSeek;一个 OpenAI SDK 经 /v1/chat/completions 打过来,也能路由到 Claude。协议是接口形状,模型字段才是真正决定谁来推理的那个值。

# chat completions 形状
curl -s https://api.kkaiapi.com/v1/chat/completions \
  -H "Authorization: Bearer $KKAIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":8,
       "messages":[{"role":"user","content":"回复 ok"}]}'

# messages 形状
curl -s https://api.kkaiapi.com/v1/messages \
  -H "x-api-key: $KKAIAPI_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":8,
       "messages":[{"role":"user","content":"回复 ok"}]}'

2026 年新写代码该选哪种协议

默认选 chat completions。这是能被普遍提供的协议,每一个网关、代理、自部署运行时都接受,也是能让模型选择保持为一个配置值的写法。把集成结构设计成 base_url 和模型 ID 都来自配置,同一份代码就能按字符串寻址 GPT、Claude、DeepSeek 或 Gemini 家族的模型。 工具本身就是 Claude 原生的时候选 Messages,经一个实现了这套协议的端点路由,能拿到网关的经济性而不用重写代码。kkaiapi 的 /v1/messages 就是为这个场景准备的:Anthropic SDK 只改一个 base_url,行为不用改。 如果自己在维护一个别人会拿去接自己端点的工具:优先说 chat completions,把其它协议做成可选项,这正是多数成熟多协议网关遵循的模式。

常见问题