Responses API 与 Chat Completions 对比

Responses API 和 Chat Completions 都可以把输入发送给语言模型，但两者组织输入、输出、工具和流式事件的方式不同。选择协议时，应先确认客户端和模型的真实契约，而不是默认“更新的端点”一定适用于所有供应商。

最短的判断方式是：

• 已经依赖 Responses Item、工具事件和 Responses 流式生命周期的编程 Agent 或应用，优先使用 Responses API；
• 传统聊天客户端，或只通过原始 Chat Completions 兼容接口开放的模型家族，优先使用 Chat Completions。

具体模型支持哪一种格式，应以模型与价格页面为准。

两种协议的核心差异

判断维度	Responses API	Chat Completions
主要输入结构	input 与不同类型的输入项	messages 数组
输出结构	不同类型的输出项和事件	Assistant Message、Choice 与 Delta
流式格式	Responses 事件流	Chat Completion Chunk
工具活动	工具调用和工具输出项	附着在 Assistant Message 上的 Tool Call
更常见场景	Agent、编程工具和 Responses 原生应用	聊天客户端与广泛兼容的 OpenAI 风格供应商
模型可移植性	只适用于已验证支持 Responses 的模型	只适用于已验证支持 Chat Completions 的模型

这张表说明的是 Wire Contract，并不表示 Modelflare 会自动转换所有供应商能力。

什么时候优先使用 Responses API

如果客户端把一次模型运行理解成一系列不同类型的 Item，而不是一条 Assistant Message，应选择 /v1/responses。这在编程 Agent 中很常见，因为客户端需要区分可见文本、推理摘要、函数参数、自定义工具输入等不同事件。

最小请求示例：

curl -sS https://modelflare.dev/v1/responses \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "列出 API 迁移前应该做的三项检查。",
    "stream": true
  }'

Responses 流式能力必须端到端验证。只理解 Chat Completions Chunk、却不理解 Responses Event 的客户端，可能能够成功连接，但最终无法正确展示输出。

什么时候 Chat Completions 更稳妥

如果应用围绕 system、user、assistant 和 tool Message 构建，或者目标供应商只声明支持 OpenAI 兼容的 Chat Completions，应选择 /v1/chat/completions。

curl -sS https://modelflare.dev/v1/chat/completions \
  -H "Authorization: Bearer $MODELFLARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "system", "content": "请简洁回答。"},
      {"role": "user", "content": "API 健康检查应该验证什么？"}
    ],
    "stream": true
  }'

对于非 OpenAI 模型家族，Modelflare 可以通过原始 Chat Completions 透传，把供应商私有的推理、搜索等字段原样送到上游。这是一项明确收窄的兼容策略，并不等于已经支持完整 Responses 协议。

不要只根据模型名称选择协议

必须分别确认三件事：

1. API Key 可以访问该模型。 权限取决于 Key 和可用分组；
2. 模型支持所选端点。 出现在 /v1/models 中，不代表同时支持两种格式；
3. 客户端理解对应流。 Responses Event 与 Chat Completions Chunk 是两种不同客户端契约。

任何一项没有确认，只替换端点路径都可能把清晰的兼容错误变成空响应或只渲染一部分的响应。

迁移工具和结构化输出

移动现有集成前，应检查：

• 客户端使用的工具定义结构；
• Tool Call ID 与 Tool Output 的返回方式；
• 显式可选值是否会把 0 或 false 丢掉；
• 供应商是否要求必须原样透传的私有字段；
• 只有工具调用、没有可见文本的响应；
• 客户端如何判断完成状态和读取 Usage。

同一提示词返回相似文字，并不是完整的协议测试。真正的验证必须覆盖应用依赖的功能。

一套可复用的选择流程

1. 在模型与价格中选择模型和分组；
2. 确认支持的 API 格式；
3. 如果已有对应客户端文档，按 Modelflare 文档完成配置；
4. 发送一条非流式请求；
5. 发送一条流式请求；
6. 验证工具或结构化输出；
7. 在用量日志中检查状态、时序、Token 和费用。

Responses API 不是所有场景下对 Chat Completions 的替代品，Chat Completions 也没有失效。正确的协议，是客户端、所选模型和上游供应商契约三者都明确支持的协议。