如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

迁移到 Responses API

Responses API 是在 Chat Completions 基础上发展而来的新一代基础 API。它简化了集成过程,并提供了构建智能体所需的强大基础能力。

我们仍然支持 Chat Completions,并建议所有新项目使用 Responses。

关于 Responses API

Responses API 提供统一的接口,帮助您构建具备智能体能力的应用。它支持以下功能:

Responses 的优势

与 Chat Completions 相比,Responses API 有以下优势:

  • 模型表现更好:GPT-5 等推理模型在 Responses 中的表现优于在 Chat Completions 中的表现。在内部评估中,使用相同的提示词和设置时,SWE-bench 成绩提高了 3%。
  • 默认支持智能体循环:在一次 API 请求中,模型可以调用多个工具,例如 web_search、image_generation、file_search、code_interpreter、远程 MCP 服务器,以及您自定义的函数。
  • 成本更低:更高的缓存利用率降低了成本。在内部测试中,缓存利用率比 Chat Completions 提高了 40% 至 80%。
  • 跨轮次保留上下文:使用 store: true 可以在轮次之间保留状态,包括推理和工具调用的上下文。
  • 输入灵活:可以通过 input 传入字符串或消息列表。在 developer 消息中指定持续生效的规则,通过顶层 instructions 指定仅适用于本次响应的指令。
  • 加密推理:无需存储状态即可使用高级推理功能。
  • 支持未来的模型:Responses 的设计考虑了对即将推出的模型的支持。
功能 Chat Completions API Responses API
文本生成
音频 即将推出
视觉
结构化输出
函数调用
网页搜索
文件搜索
计算机使用
代码解释器
MCP
图像生成
推理摘要

示例

以下示例展示了 Responses API 和 Chat Completions API 在具体场景中的差异。

消息与条目

两种 API 都可以调用我们的模型生成输出。Chat Completions 调用的输入和返回结果都是消息数组,而 Responses API 使用条目。条目是一个联合类型,其成员类型涵盖模型可能执行的各种操作。message 是一种条目类型,function_call 和 function_call_output 也是。Chat Completions 的消息对象将多种信息放在一起,而 Responses 用不同的条目分别表示这些信息,更贴合模型上下文的基本组成单位。

此外,Chat Completions 可以通过 choices 返回多个并行生成的结果,数量由 n 参数指定。Responses API 没有这个参数,每次只返回一个生成结果。

Chat Completions API
from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-6.2-astra",
    messages=[
        {
            "role": "user",
            "content": "Write a one-sentence bedtime story about a unicorn.",
        }
    ],
)

print(completion.choices[0].message.content)
Responses API
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.2-astra",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

Responses API 返回的字段略有不同。原先返回的是 message,现在您会收到一个有明确类型的 response 对象,它有自己的 id。Responses 默认存储响应。对于新账户,Chat Completions 也默认存储生成结果。使用任一 API 时,都可以设置 store: false 来禁用存储。

这两种 API 返回的对象结构略有不同。Chat Completions 返回一个 choices 数组,每个元素包含一条 message。Responses 返回一个名为 output 的条目数组。

Chat Completions API
{
  "id": "chatcmpl-C9EDpkjH60VPPIB86j2zIhiR8kWiC",
  "object": "chat.completion",
  "created": 1756315657,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Under a blanket of starlight, a sleepy unicorn tiptoed through moonlit meadows, gathering dreams like dew to tuck beneath its silver mane until morning.",
        "refusal": null,
        "annotations": []
      },
      "finish_reason": "stop"
    }
  ],
  ...
}
Responses API
{
  "id": "resp_68af4030592c81938ec0a5fbab4a3e9f05438e46b5f69a3b",
  "object": "response",
  "created_at": 1756315696,
  "model": "gpt-5.5",
  "output": [
    {
      "id": "rs_68af4030baa48193b0b43b4c2a176a1a05438e46b5f69a3b",
      "type": "reasoning",
      "content": [],
      "summary": []
    },
    {
      "id": "msg_68af40337e58819392e935fb404414d005438e46b5f69a3b",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "Under a quilt of moonlight, a drowsy unicorn wandered through quiet meadows, brushing blossoms with her glowing horn so they sighed soft lullabies that carried every dreamer gently to sleep."
        }
      ],
      "role": "assistant"
    }
  ],
  ...
}

其他差异

  • Responses 默认存储响应。对于新账户,Chat Completions 也默认存储生成结果。要在任一 API 中禁用存储,请设置 store: false。
  • Responses API 为推理模型提供了更丰富的功能,包括改进的工具调用能力。从 GPT-5.4 开始,只有当 reasoning_effort 为 none 时,Chat Completions 才支持工具调用。
  • 结构化输出的 API 格式有所不同。请将 response_format 替换为 Responses 中的 text.format。详情请参阅结构化输出指南。
  • 函数调用的 API 格式有所不同,涉及请求中的函数配置以及响应中返回的函数调用。完整对比请参阅函数调用指南。
  • Responses SDK 提供 output_text 辅助属性,而 Chat Completions SDK 没有这一属性。
  • 在 Chat Completions 中,您必须手动管理对话状态。Responses API 支持使用 Conversations API 持久保存对话,您也可以传入 previous_response_id 将多个响应串联起来。

从 Chat Completions 迁移

迁移涉及三项相关改动:将请求发送到 /v1/responses,从包含不同类型条目的 output 数组中读取输出,并确定应用如何在轮次之间传递状态。

1. 更新生成端点

首先,将生成端点从 post /v1/chat/completions 改为 post /v1/responses。

如果您没有使用函数或多模态输入,原有的纯文本消息输入可以在两种 API 中通用:

复用纯文本消息输入
const context: { role: "system" | "user"; content: string }[] = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "Hello!" },
];

const completion = await client.chat.completions.create({
  model: "gpt-6.2-astra",
  messages: context,
});

const response = await client.responses.create({
  model: "gpt-6.2-astra",
  input: context,
});

使用 Chat Completions 时,您需要创建 messages 数组,并从 completion.choices[0].message.content 读取模型生成的文本。

使用模型生成文本
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const completion = await client.chat.completions.create({
  model: "gpt-6.2-astra",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" },
  ],
});
console.log(completion.choices[0].message.content);

2. 将消息映射为条目

Chat Completions 使用 messages 表示输入和输出。Responses 则使用 input 和 output 数组,其中每个条目都有明确的类型。message 是一种条目类型,其他类型包括 reasoning、function_call 和 function_call_output。

Chat Completions 中的概念 Responses 中的对应形式
messages[] input,可以是字符串或输入条目数组
系统或开发者指令 将持续生效的规则写入第一条 developer 消息,并将该消息放在 input 中。仅适用于单轮的指令通过顶层 instructions 指定
用户消息 带有 role: "user" 的输入消息条目
助手消息 response.output 中的输出消息条目。如果您手动管理状态,请通过 input 将该条目传回
工具调用或函数调用 function_call 输出条目
工具或函数的返回结果 function_call_output 输入条目,通过 call_id 与相应调用关联
使用 n 生成多个结果 Responses 不支持此参数。如果需要多个候选输出,请分别发送请求

如果只需要最终文本,请使用 SDK 的 output_text 辅助属性。如果流程涉及推理、工具或多模态输出,请遍历 response.output,根据每个条目的 type 分别处理。

3. 更新多轮对话

如果您的应用支持多轮对话,请更新上下文管理逻辑。Responses 提供三种常用的状态管理方式:

  • 如果希望由 OpenAI 管理先前响应的上下文,请使用 previous_response_id。在首次请求中,将持续生效的规则写入第一条 developer 消息,并通过 input 传入。响应链中的后续响应会继承这条消息。仅适用于当前轮次的指令通过顶层 instructions 指定。
  • 如果需要自行管理或裁剪上下文,请在下一次请求中传回先前的 output 条目。
  • 如果需要持久保存的对话对象,请使用 Conversations API。

在 Chat Completions 中,您需要保存对话记录,并在每次请求中发送包含迄今所有消息的 messages 数组。

多轮对话
let messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "What is the capital of France?" },
];
const res1 = await client.chat.completions.create({
  model: "gpt-6.2-astra",
  messages,
});

messages = messages.concat([res1.choices[0].message]);
messages.push({ role: "user", content: "And its population?" });

const res2 = await client.chat.completions.create({
  model: "gpt-6.2-astra",
  messages,
});

即使使用 previous_response_id,API 仍会将响应链中先前各轮的所有输入 Token 按输入 Token 计费。

4. 确定何时存储状态

Responses 默认存储响应。对于新账户,Chat Completions 也默认存储生成结果。要在任一 API 中禁用存储,请设置 store: false。

受合规要求或数据保留政策限制,有些组织无法以有状态方式使用 Responses API,例如有零数据保留(ZDR)要求的组织。为满足这类需求,OpenAI 提供了加密推理条目,让您在保持工作流无状态的同时仍能利用推理条目。

要在停用状态存储后继续使用推理功能,请按以下步骤操作:

  • 设置 store: false,详见 store 字段。
  • 保留并在后续请求中传回每一个返回的推理条目。创建响应时,每个推理条目默认都包含 encrypted_content。

这样,API 会返回加密后的推理 Token。您可以像传回普通推理条目一样,在后续请求中将其传回。 对于有 ZDR 要求的组织,OpenAI 会自动强制设置 store: false。如果请求包含 encrypted_content,OpenAI 会在内存中将其解密,用于生成下一个响应,随后安全丢弃解密后的内容。所有新生成的推理 Token 都会立即加密并返回给您,确保中间状态不会被持久保存。

5. 更新函数定义和输出

Chat Completions 与 Responses 的函数定义有两处不同:

  1. Chat Completions 将类型标记放在函数定义对象外部。Responses 将类型标记放在函数定义对象内部。
  2. 在 Chat Completions 中,函数默认使用非严格模式。在 Responses 中,如果省略 strict,API 会尝试使用严格模式。如果无法使函数的参数模式与严格模式兼容,Responses 会退回到非严格模式,尽可能按定义调用函数,并在返回的最终工具定义中标明 strict: false。如果要明确让 Responses 保持非严格模式,请设置 strict: false。

右侧的 Responses API 函数示例与左侧的 Chat Completions 示例在功能上等效。

Chat Completions API
{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Determine weather in my location",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "location"
      ]
    }
  }
}
Responses API
{
  "type": "function",
  "name": "get_weather",
  "description": "Determine weather in my location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string"
      }
    },
    "additionalProperties": false,
    "required": [
      "location"
    ]
  }
}

遵循函数调用最佳实践

在 Responses 中,工具调用及其输出属于两种不同的条目类型,通过 call_id 关联。要详细了解 Responses 中函数调用的工作方式,请参阅函数调用文档。

6. 更新结构化输出定义

在 Responses API 中,结构化输出定义已从 response_format 移至 text.format:

结构化输出
const completion = await openai.chat.completions.create({
  model: "gpt-6.2-astra",
  messages: [
    {
      role: "user",
      content: "Jane, 54 years old",
    },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: {
            type: "string",
            minLength: 1,
          },
          age: {
            type: "number",
            minimum: 0,
            maximum: 130,
          },
        },
        required: ["name", "age"],
        additionalProperties: false,
      },
    },
  },
  reasoning_effort: "medium",
});

7. 更新流式响应处理逻辑

Chat Completions 的流式响应返回包含 delta 字段的增量数据块。Responses 的流式响应使用有明确类型的服务器发送事件。请更新处理逻辑,根据每个事件的 type 选择相应的分支,处理界面或编排层所需的事件。

对于流式文本输出,可以监听的事件包括:

  • response.created
  • response.output_text.delta
  • response.completed
  • error

函数调用的事件流还可能产生 response.function_call_arguments.delta 和 response.function_call_arguments.done 等事件。请参阅 Responses 流式响应指南和 Responses 流式事件参考文档。

8. 改用原生工具

如果您的应用有适合使用 OpenAI 原生工具的场景,可以更新工具调用,直接使用 OpenAI 提供的工具。

Chat Completions 不支持直接使用 OpenAI 托管的工具,您需要自行编写工具集成代码。 本例使用 GPT-5.6 Terra,并已禁用推理。GPT-6 Astra 和 GPT-6.1 Sol 必须通过 Responses API 调用工具。

网页搜索工具
async function web_search(query: string) {
  const res = await fetch(`https://api.example.com/search?q=${query}`);
  const data = await res.json();
  return data.results;
}

const completion = await client.chat.completions.create({
  model: "gpt-5.6-terra",
  reasoning_effort: "none",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Who is the current president of France?" },
  ],
  functions: [
    {
      name: "web_search",
      description: "Search the web for information",
      parameters: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"],
      },
    },
  ],
});

9. 排查常见迁移错误

将代码从 Chat Completions 迁移到 Responses 时,请留意以下问题:

  • 仍然读取 choices[0].message.content,而没有改为读取 response.output_text 或 response.output。
  • 将 output 中的每个条目都当作消息处理。推理、工具调用和函数调用分别有各自的条目类型。
  • 手动将上下文传入下一轮以生成响应时,遗漏了推理、函数调用或函数调用输出条目。
  • 发送函数结果时未包含匹配的 call_id。
  • 在 Responses 请求中仍然使用 response_format,而没有改用 text.format。
  • 复用 Chat Completions 的流式数据块处理逻辑,却未按类型处理 Responses 事件。
  • 误以为使用 previous_response_id 后,先前的上下文就不再计费。响应链中先前各轮的输入 Token 仍按输入 Token 计费。

分阶段上线检查清单

我们仍然支持 Chat Completions,因此您可以每次迁移一个用户流程。

  • 从一个文本生成流程开始。
  • 更新端点、请求体和输出处理逻辑。
  • 确定流程使用哪种方式管理状态:使用 previous_response_id、手动传回条目,或使用 Conversations API。
  • 如果流程无状态或有 ZDR 要求,请添加 store: false,并在需要跨轮次保留推理上下文时传入加密推理条目。
  • 迁移函数定义,并验证函数调用输出是否包含正确的 call_id。
  • 将结构化输出模式从 response_format 移至 text.format。
  • 更新流式响应处理逻辑,按类型处理 Responses 事件。
  • 在适合的工作流中,使用 OpenAI 托管的工具替换自定义编排逻辑。
  • 在将更多流量转到 Responses 之前,对比迁移前后的行为、延迟、Token 用量和错误情况。

我们建议逐步将所有流程迁移到 Responses API,以便使用 OpenAI 的最新功能和改进。

Assistants API

根据开发者在 Assistants API 测试期间提供的反馈,我们在 Responses API 中引入了多项重要改进,使其更灵活、速度更快,也更易于使用。Responses API 是未来在 OpenAI 平台上构建智能体的发展方向。

Assistants API 已于 2026 年 8 月 26 日正式停止服务,现已无法使用。请按照迁移指南将您的集成迁移到 Responses API。