OpenAI Chat Completions 与 Responses API 协议差异

一、OpenAI 老协议：Chat Completions

1.1 协议定位

Chat Completions 以 messages[] 表示对话历史，模型返回结果主要位于 choices[]。它适合已有聊天应用、兼容 OpenAI Chat API 的客户端和相对稳定的文本/工具调用流程。

项目 Chat Completions
Endpoint POST /v1/chat/completions
输入 messages[]，通过 role 区分 system、user、assistant、tool
输出 choices[].message
最大输出 max_completion_tokens
结构化输出 response_format
Usage prompt_tokens、completion_tokens、total_tokens
流式 chat.completion.chunk，从 choices[].delta 聚合

1.2 请求 JSON

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "你是一个简洁的技术助手。"
    },
    {
      "role": "user",
      "content": "用一句话解释 SSE。"
    }
  ],
  "max_completion_tokens": 200,
  "stream": false
}

1.3 响应 JSON

{
  "id": "chatcmpl_demo_001",
  "object": "chat.completion",
  "created": 1788777600,
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "SSE 是服务器通过一个持续的 HTTP 连接向客户端单向推送事件的协议。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 28,
    "total_tokens": 53
  }
}

1.4 工具调用 JSON

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_weather_001",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"上海\",\"date\":\"2026-09-08\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

{
  "role": "tool",
  "tool_call_id": "call_weather_001",
  "content": "{\"temperature_c\":29,\"condition\":\"多云\"}"
}

1.5 流式 JSON

data: {"id":"chatcmpl_demo","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl_demo","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]}

data: {"id":"chatcmpl_demo","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

二、OpenAI 新协议：Responses API

2.1 协议定位

Responses API 面向推理、工具调用和 Agent 工作流，将输入和输出统一建模为带类型的 Item。响应可能包含 message、reasoning、function_call 以及其他工具相关 Item，因此不能把它简化成单个 assistant 文本。

项目 Responses API
Endpoint POST /v1/responses
输入 input 字符串或 Item 数组；顶层指令可放在 instructions
输出 output[]，每个元素是有类型的 Item
最大输出 max_output_tokens
结构化输出 text.format
上下文 可手动传递，也可使用 previous_response_id 或 Conversation
流式 按事件 type 分发，如 response.output_text.delta、response.completed
生命周期 支持响应状态、后台执行、查询、取消和其他长任务能力

2.2 请求 JSON

{
  "model": "MODEL_ID",
  "instructions": "你是一个简洁的技术助手。",
  "input": "用一句话解释 SSE。",
  "max_output_tokens": 200,
  "stream": false
}

2.3 响应 JSON

{
  "id": "resp_demo_001",
  "object": "response",
  "created_at": 1788777600,
  "status": "completed",
  "model": "MODEL_ID",
  "output": [
    {
      "id": "msg_demo_001",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "SSE 是服务器通过一个持续的 HTTP 连接向客户端单向推送事件的协议。",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 28,
    "total_tokens": 53
  }
}

实现侧优先使用 SDK 提供的 output_text 聚合能力，或者遍历 output[] 并按 Item 类型处理。不要固定读取 output[0].content[0].text。

2.4 多轮上下文 JSON

{
  "model": "MODEL_ID",
  "previous_response_id": "resp_demo_first_turn",
  "instructions": "你是订单助手。",
  "input": "我的订单号是什么？"
}

使用 previous_response_id 时，当前请求应重新传入需要生效的 instructions。链路历史仍可能影响输入 token 统计。

2.5 工具调用 JSON

{
  "id": "resp_weather_001",
  "status": "completed",
  "output": [
    {
      "id": "fc_weather_001",
      "type": "function_call",
      "status": "completed",
      "call_id": "call_weather_001",
      "name": "get_weather",
      "arguments": "{\"city\":\"上海\",\"date\":\"2026-09-08\"}"
    }
  ]
}

{
  "model": "MODEL_ID",
  "previous_response_id": "resp_weather_001",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_weather_001",
      "output": "{\"temperature_c\":29,\"condition\":\"多云\"}"
    }
  ]
}

2.6 流式事件 JSON

event: response.created
data: {"type":"response.created","response":{"id":"resp_demo","status":"in_progress"}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_demo","type":"message","status":"in_progress","role":"assistant","content":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_demo","output_index":0,"content_index":0,"delta":"你好"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_demo","status":"completed","output":[]}}

三、OpenAI Image 2

3.1 协议定位

本节将 Image 2 按 OpenAI GPT Image 2 处理。它是图片生成和编辑模型，核心返回结果是图片媒体数据，不应沿用文本聊天接口的 choices[].message.content 或 output[].content[].text 读取逻辑。

项目 GPT Image 2
生成 Endpoint POST /v1/images/generations
编辑 Endpoint POST /v1/images/edits
输入 文本 prompt；编辑场景还包括 image、mask 等 multipart 文件
输出 data[] 媒体结果，通常包含 Base64 图片数据或可访问 URL
流式 图片生成接口不能直接按文本 delta 聚合
工具调用 图片生成模型本身不等同于 function calling 模型

3.2 图片生成请求 JSON

{
  "model": "gpt-image-2",
  "prompt": "一张极简技术架构图，展示 Chat Completions、Responses、GPT Image 2 和 Claude 的协议边界，白色背景，清晰标签。",
  "n": 1,
  "size": "1536x1024",
  "quality": "high",
  "background": "opaque",
  "output_format": "png"
}

3.3 图片生成响应 JSON

{
  "created": 1788777600,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "一张白色背景、极简技术风格的协议架构图..."
    }
  ]
}

3.4 图片编辑 multipart 示例

Content-Type: multipart/form-data

model=gpt-image-2
image=@architecture.png
mask=@mask.png
prompt=保留原有布局，把右侧节点改成 Claude Messages
size=1536x1024
quality=high

网关需要独立处理 Base64 解码、对象存储、图片大小、multipart 文件、临时文件清理和媒体安全扫描。不要把大段 Base64 写入普通文本日志或拼进聊天上下文。

四、Claude：Messages API

4.1 协议定位

Claude Messages API 通过 messages[] 表示无状态多轮消息，系统指令通常放在顶层 system 字段。返回值以 content[] 内容块为核心，可包含 text、tool_use、thinking 或其他块类型。

项目 Claude Messages
Endpoint POST https://api.anthropic.com/v1/messages
版本请求头 anthropic-version: 2023-06-01
输入 顶层 system + messages[]，每条消息包含 role 和 content
输出 content[] 内容块
最大输出 max_tokens
工具调用 tool_use，工具结果通过 tool_result 回传
流式 命名 SSE 事件，如 message_start、content_block_delta、message_stop

4.2 请求 JSON

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": "你是一个简洁的技术助手。",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "用一句话解释 SSE。"
        }
      ]
    }
  ],
  "stream": false
}

x-api-key: $ANTHROPIC_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

4.3 响应 JSON

{
  "id": "msg_demo_001",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-5",
  "content": [
    {
      "type": "text",
      "text": "SSE 是服务器通过一个持续的 HTTP 连接向客户端单向推送事件的协议。"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 25,
    "output_tokens": 28
  }
}

4.4 工具调用 JSON

{
  "id": "msg_weather_001",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "我先查询天气。"
    },
    {
      "type": "tool_use",
      "id": "toolu_weather_001",
      "name": "get_weather",
      "input": {
        "city": "上海",
        "date": "2026-09-08"
      }
    }
  ],
  "stop_reason": "tool_use"
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_weather_001",
      "content": "{\"temperature_c\":29,\"condition\":\"多云\"}"
    }
  ]
}

Claude 的工具结果放在新的 user 消息中，通过 tool_use_id 关联先前的工具调用。它与 Chat Completions 的 role=tool 和 Responses 的 function_call_output 不是同一种协议结构。

4.5 流式事件 JSON

event: message_start
data: {"type":"message_start","message":{"id":"msg_demo","type":"message","role":"assistant","content":[],"usage":{"input_tokens":25,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你好"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":1}}

event: message_stop
data: {"type":"message_stop"}

五、横向对比总结

5.1 协议字段对比

维度 OpenAI 老：Chat OpenAI 新：Responses Claude
主用途 稳定聊天协议 推理、Agent、工具和状态 文本、多模态和工具对话
输入 messages[] input / Item[] system + messages[]
文本输出 choices[].message.content output[] 中的 message 或 output_text content[] 中的 text block
工具调用 tool_calls[] type=function_call type=tool_use
工具****结果 role=tool function_call_output tool_result 放在 user 消息
最大输出 max_completion_tokens max_output_tokens max_tokens
流式事件 choices[].delta response.* 事件 message_* / content_block_*
输入 Token prompt_tokens input_tokens usage.input_tokens
状态****管理 客户端重发历史 支持 response 链和 Conversation 主要由客户端维护无状态 messages

5.2 最重要的结论

  1. Chat Completions 是消息协议：核心是 messages、choices 和 delta，兼容性最好，迁移成本最低。

  2. Responses 是 Item 和生命周期协议：核心是 input、output、事件 type、response status 和工具/状态链路，更适合 Agent 化工作流。

  3. GPT Image 2 是媒体协议：核心结果是图片数据，网关需要处理 Base64、URL、multipart 和媒体存储，不能当作文本聊天协议。

  4. Claude 是内容块协议：核心是 content block、tool_use/tool_result 和 Anthropic SSE，字段结构与 OpenAI 两套协议都不完全兼容。

  5. 工具调用不能只做字段改名：三者的调用对象、结果回传 role/type 和关联 ID 都不同，需要显式适配。

  6. SSE 不能共用一个简单解析器：应按 provider 和事件类型分发，再归一化为内部 StreamEvent。

选型建议：存量聊天客户端优先保留 Chat Completions；新建 Agent、推理、内置工具或长任务优先 Responses；图片生成/编辑单独走 Image 2 媒体链路；Claude 接入单独保留 Anthropic Messages 适配层。

六、官方资料

以下资料用于继续核对字段、模型能力和版本变化。

https://developers.openai.com/api/docs/guides/migrate-to-responses

https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create/

https://developers.openai.com/api/reference/resources/responses/methods/create/

https://developers.openai.com/api/docs/models/gpt-image-2

https://developers.openai.com/api/docs/guides/image-generation

https://platform.claude.com/docs/en/api/messages

https://platform.claude.com/docs/en/api/messages/create

https://platform.claude.com/docs/en/build-with-claude/streaming

posted @ 2026-09-03 17:49  alin_qu  阅读(32)  评论(0)    收藏  举报