先给结论：Responses 还是 Chat Completions，不取决于哪个接口更新，而是由 客户端、模型、网关三者共同决定。客户端决定你能发出什么请求，模型决定哪个端点能提供所需能力，网关决定这条请求能否原样到达上游。
所以，不要为了接一个新模型就强行改接口。记住这句判断：客户端不支持，再新的接口也不要用；模型只支持一个端点，就不要硬套另一个。 下面的 7 项检查、场景决策表和回滚清单，可以帮你在上线前发现工具调用、推理参数或流式事件的不兼容。
Responses 和 Chat Completions 到底差在哪
两种接口的核心差别在于数据模型：Chat Completions 围绕消息数组，Responses 围绕响应对象。
Chat Completions 的请求以 messages 为中心，每条消息带 role 和 content，常见字段还有 temperature、max_tokens、tools、stream。它是无状态的，历史由调用方维护，响应则从 choices 里取 message、finish_reason，用量看 usage。它的 SDK 和客户端支持面最广。
Responses 的请求以 input 为中心，可以带 tools、reasoning、previous_response_id，响应里是 output 数组、output_text、status、id 和 usage。部分新推理模型和工具能力只在 Responses 提供，但不是所有模型、SDK、客户端和网关都支持它。
| 检查项 | Chat Completions | Responses | 迁移风险 |
|---|---|---|---|
| 端点与请求形状 | /v1/chat/completions，使用 messages |
/v1/responses，使用 input |
路径或请求体不匹配，解析代码失效 |
| 多轮状态 | 调用方全量传历史 | 可用 previous_response_id 引用上一轮 |
状态过期、上下文不一致 |
| 推理与 token 参数 | max_tokens 或 max_completion_tokens |
通过 reasoning 配置推理 |
参数被忽略或直接报错 |
| 工具调用 | tools 加消息内的工具结果 |
output 中的工具项加对应结果项 |
调用 ID 配对错误，Agent 循环中断 |
| 流式事件 | SSE 增量片段 | 带类型的 SSE 事件 | 提前结束、文本拼接错误 |
| 多模态输入 | 常见 image_url 内容片段 |
常见 input_image 等输入项 |
图片或文件被拒绝 |
| 兼容性 | 客户端和网关覆盖广 | 取决于客户端、网关和模型 | 能填 Base URL，却调不通端点 |
选择时按这个顺序判断，三者冲突时，优先保证客户端和模型能跑通：
- 先看客户端：它支持 Chat Completions、Responses，还是厂商原生格式。
- 再看模型：目标模型是否只在某个端点提供，是否依赖内置工具或推理项。
- 再看网关：是否代理目标端点，能否做模型映射和日志记录。
- 最后看成本：同样的任务，两种接口的 token、缓存和重试成本是否不同。
接入建议：对比表只能帮你定位风险，具体模型支持哪个端点，还要回到实际环境确认。可以先在 API易 apiyi.com 控制台查看目标模型，再决定走哪条验证路径。
请求层怎么查：Responses 接入的检查 1-3
请求层的结论很简单：端点、状态和参数三项没对齐，后面的工具和流式都不用测。
检查 1：Responses 与 Chat Completions 的端点和请求形状
这一项要确认的是，请求发到了正确路径，请求体和响应解析也都换成了对应结构。
- 差异：一个走
/v1/chat/completions，一个走/v1/responses；前者传messages、读choices，后者传input、读output。 - 容易踩的坑：只改路径、不改解析。请求可能已经成功，业务代码却取不到
choices[0].message，表面上看像是模型没有返回内容。 - 怎么验证：用一条最小文本请求分别打两个端点，记录状态码、响应顶层字段和
usage。走 API易 的 OpenAI 兼容接口时，Base URL 使用https://api.apiyi.com/v1，目标端点和模型是否可用以控制台和文档为准。 - 怎么选：模型两边都支持、业务只需要文本时，继续用现有接口；模型只开放某个端点时，就按该端点改造。
检查 2：Chat Completions 与 Responses 的多轮状态管理
状态放在哪里，决定了排障方式，也影响上下文的可控程度。
- 差异：Chat Completions 每轮传完整
messages；Responses 可以用previous_response_id引用上一轮响应，把部分状态交给服务端。 - 容易踩的坑：把少传内容等同于少计费。历史上下文是否继续计入输入 token，要以官方文档和实际账单为准。另一个坑是状态过期，长任务恢复时，旧的 response id 可能已经无法使用。
- 怎么验证：连续跑三轮对话，确认第三轮能引用第一轮的信息；再用一个放置较久的 id 测试失败路径，看错误是否可识别。网关背后如有多条上游线路，还要确认 id 能否跨请求继续使用，以网关支持为准。
- 怎么选：需要完全掌控上下文、方便审计和裁剪时，全量传历史更直接；长对话或 Agent 循环确实能从服务端状态受益时，再评估 Responses。
检查 3：Responses 迁移时的推理与 token 参数
参数最大的风险往往不是报错，而是被静默忽略，请求成功了，推理配置却没有生效。
- 差异：
max_tokens在部分新模型上已被max_completion_tokens取代，旧字段可能被忽略或报错。推理强度在不同厂商、不同接口上的名称也不同，常见的有 reasoning effort 和thinking等形式。 - 容易踩的坑：把一套参数模板用于所有模型。客户端或网关如果丢弃了未知字段，返回看起来正常，推理深度和输出上限却可能不是你设定的值。
- 怎么验证：逐个改变输出上限和推理强度，对比返回长度、
usage和错误信息。没有差异时，先怀疑参数未被透传或未被该模型支持，再查官方文档和网关说明。 - 怎么选：按“模型 + 端点”维护参数映射表，不按厂商粗略归类。业务依赖
reasoning配置时，优先选择能原样传递该字段的接口路径。
能力层怎么查：Chat Completions 迁移的检查 4-6
能力层的结论是：两种接口都可能跑通同一个功能，但解析代码基本不能直接复用。
检查 4：Chat Completions 与 Responses 的工具调用
Chat Completions 支持工具调用，真正要迁移的是工具 schema、调用 ID 和结果回传方式。
- 差异：两者都有工具定义，但结构不同。Chat Completions 的调用通常出现在 assistant 消息的
tool_calls中；Responses 的调用作为output项返回，结果也要用对应的输入项回传。具体字段以官方文档为准。 - 容易踩的坑：并行调用时只处理第一个工具，或把调用 ID 改写后再回传。模型下一轮可能报错，也可能拿错结果继续推理，后者更难排查。
- 怎么验证：准备一个单工具用例和一个并行工具用例，检查每个调用 ID 是否原样回传、结果是否一一配对。再故意让工具返回失败，确认 Agent 循环能正常收尾。
- 怎么选：现有工具链稳定、没有内置工具需求时，留在 Chat Completions；目标模型的内置工具只在 Responses 提供时，再迁移并重写解析层。
检查 5：Responses 与 Chat Completions 的流式事件
流式不能只看“有没有吐字”，结束和错误处理同样要验证。
- 差异：两者都基于 SSE，但事件类型和结束标记不同。Chat Completions 以增量片段为主，Responses 通过不同类型的事件区分文本、工具和完成状态。
- 容易踩的坑：用“收到
data就结束”判断完成，或者只拼接文本增量、不处理工具参数增量和错误事件。结果可能是回答被截断，工具参数也拼不完整。 - 怎么验证：抓取一次完整 SSE 原文，核对增量顺序、结束事件、
usage出现位置和中途错误的表现。网关如果转换或缓冲事件，要在经过网关的链路上再抓一次。 - 怎么选：客户端的流式解析器只认 Chat Completions 格式时，不要直接切到 Responses；要切换，就先升级 SDK 或改造解析层。
检查 6：Responses 接入时的多模态输入
多模态字段由接口和厂商共同决定，文本跑通并不代表图片和文件能跑通。
- 差异：图片字段可能是
image_url、input_image或 base64，文件和音频的输入方式也会随接口、厂商变化。 - 容易踩的坑：沿用旧的内容片段结构，或者假定 URL 和 base64 都能使用。网关转换格式时，也可能遇到大小、编码或文件类型上的差异。
- 怎么验证：分别用 URL 图片、base64 图片和目标文件类型发最小请求，确认模型真的读取了内容。让模型回答一个只有看到图片才能回答的问题，比只看状态码可靠。
- 怎么选：只有图片理解需求时，优先走当前客户端已验证的格式；文件或音频能力依赖特定端点时，以官方文档和网关支持为准。
接入链路怎么查：Responses 兼容性的检查 7
链路检查的结论是：能填 Base URL，不等于客户端、SDK 和网关都支持 Responses。
检查 7：SDK、客户端与网关的 Responses 兼容性
一次请求要经过客户端、SDK、网关、模型四层，任何一层不支持，新接口都用不起来。
| 链路层 | 要确认什么 | 常见误判 |
|---|---|---|
| 客户端 | 是否支持目标端点，版本是否够新 | 有 Base URL 配置项，就以为支持 Responses |
| SDK | 是否封装目标方法和事件类型 | 请求能发出，就以为流式和工具也能解析 |
| 网关 | 是否代理目标端点，是否需要单独开通 | OpenAI 兼容，就以为覆盖所有 OpenAI 端点 |
| 模型映射 | 模型 ID 是否在列表中，是否需要映射 | 官方模型名可用，就以为网关中名称相同 |
- 差异：Chat Completions 的兼容面最广；Responses 的可用范围取决于客户端、SDK、网关和模型的组合。
- 容易踩的坑：客户端悄悄把路径拼成
/chat/completions，或者网关只代理了部分字段。排查时如果只看模型名，很容易把问题误判为模型能力不足。 - 怎么验证：先绕开业务代码，用接口调试工具发最小请求；再用客户端发同样的请求，比较实际路径、请求体和响应。
- 怎么选：链路中任何一层不支持目标端点，就先保留现有接口，或换用它实际支持的格式。
多模型场景下，网关最好能减少客户端的改造面。API易 apiyi.com 支持一个 Key 调用 OpenAI、Claude、Gemini 等多家模型，同时兼容 OpenAI API 标准以及 Claude、Gemini 原生格式，客户端可以按自身支持的协议接入，不必为每个模型单独适配一套接入配置。
模型 ID 不要凭记忆填写，也不要直接照搬其他平台的命名。迁移前到 API易 apiyi.com 控制台的模型列表确认模型 ID 和可用端点，价格和可用性同样以控制台和文档为准。这一步花费的时间很少，却能排除一大类“模型不存在”或“端点不支持”的错误。
Responses 还是 Chat Completions：按场景怎么选
按场景看，大多数简单任务留在 Chat Completions 就够了，确实依赖新能力时再转向 Responses。
| 场景 | 推荐接口 | 理由 | 还要确认什么 |
|---|---|---|---|
| 编程 Agent（Claude Code、Codex CLI、Cline 等） | 按客户端支持的格式选择 | 客户端的协议实现决定可用路径，多数仍以 Chat Completions 或 Anthropic Messages 为主 | 当前版本的协议配置、工具调用和流式解析 |
| 新 OpenAI 推理模型加内置工具 | 优先 Responses | 部分推理和工具能力只在 Responses 提供 | 网关是否代理端点，内置工具是否可用 |
| 长对话或 Agent 循环 | 可评估 Responses | 服务端状态可能减少重复传输 | 状态过期时间、一致性、实际 token 成本 |
| 自定义工具调用 | 沿用现有稳定接口 | Chat Completions 同样支持工具调用，迁移成本主要在解析层 | 并行调用、调用 ID 配对、错误回传 |
| 多模型统一接入 | 优先选支持多种格式的网关 | 避免为每个模型改一遍客户端 | 模型映射、日志、各模型的参数差异 |
| 只读问答或简单分类 | Chat Completions | 能力足够，兼容面广，改造成本低 | 输出上限参数是否适配目标模型 |
这张表的使用方法是先找场景，再看最后一列。比如目标模型只提供 Responses，而你的客户端只支持 Chat Completions，这时不应硬改字段，而要升级客户端、换客户端，或者换一个该路径可用的模型。
成本放在最后判断。Responses 未必更便宜，缓存命中、重试次数和实际 token 用量都会影响结果，只有在相同任务上对比账单，结论才有意义。
选择建议：手上有多个候选模型时，可以用同一组提示词和工具用例做对比。通过 API易 apiyi.com 用同一个 Key 切换模型，再结合新用户的免费测试额度完成小规模验证，能减少前期的接入和配置工作。
Responses 与 Chat Completions 常见问题 FAQ
这些问题的共同答案是：先看实际链路，再下结论。
Q1：新模型是不是只能用 Responses？
未必。这取决于具体模型和网关，部分新推理模型或工具能力只在 Responses 提供，也有模型继续支持 Chat Completions。接入前以官方文档和网关的模型说明为准。
Q2：Chat Completions 还能不能用工具调用？
能用。Chat Completions 支持工具调用，差别在于字段结构、结果回传格式和状态管理。迁移到 Responses 时，工具解析代码通常需要调整，不能直接复用。
Q3：网关不支持 Responses 怎么办？
先确认目标模型是否也能走 Chat Completions 或厂商原生格式；能走，就保留现有路径。模型只提供 Responses 时，需要换用支持该端点的网关或直连路径。使用 API易 apiyi.com 时，可在控制台和文档中确认目标模型的端点支持情况。
Q4：迁移后计费为什么变了？
常见原因包括上下文传递方式变化、推理 token 变化、缓存命中不同、工具调用增加轮次，以及失败重试。排查时按同一任务对比 `usage`，再到 API易 apiyi.com 的用量日志中核对模型、请求量和 token 消耗。
Q5：什么时候该回滚？
核心链路失败、工具结果错配、流式频繁截断，或者通过率、延迟、成本明显偏离基线且短期无法解释时，就该回滚。回滚标准要在迁移前定好，避免上线后临时争论。
Responses 迁移与回滚清单
迁移的结论是：小步验证、保留旧路径、用基线决定去留。
Responses 迁移前后的验证清单
- 盘点版本：列出客户端、SDK 和网关版本，确认目标端点受支持。
- 确认映射：核对端点、模型 ID、推理参数和 token 参数。
- 记录基线：保存原接口的通过率、延迟和 token 成本。
- 保留旧路径：保留原接口配置和模型 ID，用开关或环境变量切换，不要改死在代码里。
- 先验证文本：最小文本请求通过，响应解析正确。
- 再验证流式：增量拼接完整，结束事件和错误事件处理正确。
- 再验证工具：单工具、并行工具都能跑通，调用 ID 和结果配对正确。
- 最后验证多模态：图片、文件等实际用到的输入能被模型正确读取。
- 解释账单：对比 token 计费和缓存，差异能被说明。
- 小流量灰度：先放少量非关键流量，同时记录差异和失败案例。
迁移验证阶段，建议把新旧请求的结果放在一起看。API易 apiyi.com 控制台提供用量和账单查看能力，可以用日志核对灰度请求的模型、消耗是否符合预期；一旦异常，就切回原接口配置，再用失败案例复现问题。
Chat Completions 回滚触发条件
| 观察项 | 建议动作 | 回滚判断 |
|---|---|---|
| 文本请求失败 | 暂停灰度，检查端点和解析 | 短期无法修复时回滚 |
| 流式截断或不结束 | 对比原始 SSE 事件 | 影响用户输出时立即回滚 |
| 工具调用错配 | 检查调用 ID 和回传格式 | 可能产生错误操作时立即回滚 |
| 推理参数未生效 | 核对透传和模型支持 | 影响输出质量且无替代配置时回滚 |
| 成本偏离基线 | 分析 token、缓存和重试 | 超出团队预设阈值且无法解释时回滚 |
Responses 还是 Chat Completions 核心要点
- 选择顺序：先客户端，再模型，再网关，最后比较成本。
- 能力边界：Responses 适合依赖其专属能力的模型，但并非所有模型都支持。
- 工具调用：Chat Completions 能做工具调用，迁移重点在字段和配对。
- 验证顺序：先文本，再流式，再工具，最后多模态。
- 回滚前提：旧配置不删除，基线提前记录，切换靠开关完成。
总结：Responses 还是 Chat Completions 的最终判断
现有 Chat Completions 链路稳定、功能够用时，新模型能接就不必为了换接口而换接口。目标模型或内置工具依赖 Responses 时，再按 7 项检查逐层打通。最后记住这句话：客户端不支持，再新的接口也不要用；模型只支持一个端点，就不要硬套另一个。
准备动手时，可以先通过 API易 apiyi.com 确认模型 ID 和端点支持，用最小请求跑完清单，再决定是否放量。
作者：API易技术团队
技术交流：欢迎在 API易网站首页联系我们，更多接入资料可访问 docs.apiyi.com 文档中心
