OpenAI Responses API 入门：与 Chat Completions 怎么选

这篇解决什么： Responses API 是什么、何时该用、如何从 Chat Completions 迁移思路。
适合谁： 已会 API 入门（Completions），要做新产品或评估迁移的开发者。
不适合： 还没跑通第一次 API 调用的人——请先完成入门文。

上次核对方向：以 platform.openai.com / OpenAI 开发者文档当前说明为准（2026-09-18）。字段名以官方为准，下文用稳定概念说明。

快速结论

情况	更合适
新项目、要服务端托管工具、多步/推理连续性	Responses（官方对新项目更推荐）
已有 Completions、要跨云厂商可移植、逻辑极简单	继续 Chat Completions 完全合理
只要稳定 JSON 入库	先定 schema，见 JSON / Vision；传输层可选 Responses 或 Completions

Chat Completions 并未被要求立刻废弃；迁移应基于能力需求，而不是恐慌。

Responses 相对 Completions：你真正要理解的三点

1. 输入输出形态
   Completions：核心是 messages 数组。
   Responses：更偏 input → 得到带类型的 output 条目（消息、工具调用、推理相关条目等，以文档为准）。解析时不要假设「答案永远在 choices[0]」。

2. 状态怎么带
   Completions：通常自己回传完整历史。
   Responses：可用响应 id / previous_response_id 或 Conversations 一类机制串轮次（名称以官方为准），减少手搓超长 messages。

3. 工具与 Agent 心智
   Responses 更适合作为「单次模型动作 + 工具结果」的原语；多步编排见同簇 Agents 指南。本页不把 Agent 营销词当成保证可靠的产品承诺。

最小可运行示例（概念）

先装官方 SDK，Key 只放服务端（清单见 API 入门）。

import OpenAI from 'openai';

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function main() {
  const response = await client.responses.create({
    model: 'gpt-4o-mini', // 以平台当前可用模型名为准
    input: '用三句话解释什么是向量数据库。',
  });

  // 便捷字段因 SDK 版本而异；也可遍历 response.output
  console.log(response.output_text);
}

main().catch(console.error);

若你本地 SDK 尚无 responses.create，先升级官方 openai 包，并以文档中的 REST POST /v1/responses 为准。

结构化输出与多模态

• 结构化输出： 原则不变——先定 schema，再选接口；契约与校验流程见 JSON / Vision。
• 识图 / 文件： Responses 侧常见做法是把输入做成带类型的 input items（图、文件引用等）。细节以官方 multimodal 指南为准，不要把网页 ChatGPT 上传体验直接当成 API 行为。
• 流式： 流式事件形状与 Completions 不同，迁移时单独改 handler；成本与限流仍见 流式与成本。

迁移清单（可打印）

1. 新路由走 /v1/responses（或 SDK 等价方法），旧路由可并存灰度。
2. 把 messages 映射为 input / instructions（系统约束常独立于用户输入）。
3. 重写输出解析：遍历 typed output，不要只读 choices[0].message.content。
4. 工具循环：对齐 function_call 与回传的 function_call_output（call_id 必须匹配）。
5. 决定状态策略：自管历史 / previous_response_id / Conversations——三选一写进设计文档。
6. 评估 store 与隐私：默认存储策略以账号与文档为准；敏感场景显式关闭存储。
7. 回归：同一套评测题对比 Completions vs Responses（延迟、费用、工具成功率）。
8. Assistants API 若仍在用：按官方迁移指南转向 Responses，不要和新项目混用三套状态模型。

常见误区

误区	更好做法
「必须立刻弃用 Completions」	按能力迁移；简单聊天可保留
把 Responses 文当第二篇 API 入门	Key/第一次调用仍归入门文
不改解析只改 URL	必挂：output 形状变了
用 Responses 硬做向量检索	检索用 Embeddings

相关阅读

• OpenAI API Node.js 入门（Completions）
• JSON 结构化输出与 Vision
• 流式输出与成本控制
• OpenAI Embeddings 与向量检索
• OpenAI Agents 工作流
• ChatGPT 介绍
• API 分类

使用入口

• 官方文档：platform.openai.com
• 体验 ChatGPT 对话（调提示词）