Responses API vs Chat Completions API
从对象模型、状态、工具能力和迁移成本比较 OpenAI 两种主要模型调用接口。
#type / synthesis
#status / growing
#tech / ai
#resource / openai
#interface / api
Responses API vs Chat Completions API
结论先行
新建的推理、工具调用和 agentic 工作流通常优先从 responses-api 开始；成熟且稳定的 Chat Completions 集成没有必要只为“追新”立即重写。迁移依据应是所需能力、维护成本和回归评估，而不是接口名称。
关键差异
| 维度 | Responses API | Chat Completions API |
|---|---|---|
| 基本对象 | response 与多种 input/output item | messages 与 choices |
| 推理与工具工作流 | 面向新模型能力统一设计 | 适合传统消息式调用，能力依模型而异 |
| 多轮续接 | 可引用先前 response，也可自行管理 items | 通常由应用重发消息历史 |
| 输出解析 | 必须识别不同 item 类型 | 通常读取 assistant message/tool call |
| 新功能入口 | 新应用的优先入口 | 兼容现有大量集成 |
| 迁移风险 | 需要重做状态、解析和工具循环测试 | 保持现有行为的成本较低 |
选择算法
选择 Responses API，如果：
- 新项目需要推理模型、托管工具、MCP 或更丰富的 item；
- 希望用统一接口承载文本、多模态输入与工具循环；
- 团队愿意围绕 response/item 模型设计可观测性。
继续使用 Chat Completions，如果：
- 当前集成满足需求且已有完整回归测试；
- 依赖库或上游协议只接受 messages/choices；
- 当前阶段的迁移收益不足以覆盖验证成本。
迁移不是机械替换
迁移时至少重新验证：
- system/developer instructions 如何映射；
- 历史消息如何转成 input items；
- 文本之外的 output items 如何解析；
- 工具 call ID 与结果如何关联；
- streaming 事件、错误和取消如何处理；
- token、延迟、答案质量和副作用安全是否仍达标。
建议先做双跑：固定一组真实任务，让旧接口与新接口同时运行，比较成功率、成本、延迟和人工复核结果，再逐步切流。
相关笔记
- responses-api
- openai-api-platform
- openai-agent-evaluation-and-tracing
- [[chat-completion-api]]