English
主导航

推荐

入门

核心概念

Apps SDK

工具

运行与扩展

评估

实时与音频

模型优化

专业模型

正式上线

旧版 API

资源

API 仪表板

迁移至 Responses API

The Responses API 是我们全新的 API 原语，它是 Chat Completions 的演进，为您的集成带来了更高的简洁性和强大的智能体原语。

虽然 Chat Completions 仍受支持，但我们推荐在所有新项目中使用 Responses。

关于 Responses API

Responses API 是一个用于构建强大的类智能体应用的统一接口。它包含：

Responses 的优势

Responses API 相比 Chat Completions 具有以下几项优势：

  • 更高的性能：使用推理模型（如 GPT-5）配合 Responses，与 Chat Completions 相比将带来更高的模型智能。我们的内部评估显示，在相同提示词和设置下，SWE-bench 得分提高了 3%。
  • 默认具备智能体能力：Responses API 是一个智能体循环，允许模型在一个 API 请求的跨度内调用多种工具，例如 web_search, image_generation, file_search, code_interpreter、远程 MCP 服务器，以及您自定义的函数。
  • 更低的成本：由于提升了缓存利用率从而降低了成本（在内部测试中，与 Chat Completions 相比提升了 40% 到 80%）。
  • 有状态上下文：使用 store: true 用于在多轮对话间保持状态，并在轮次之间保留推理和工具上下文。
  • 灵活的输入：传入包含输入的字符串或消息列表；使用 instructions 提供系统级指引。
  • 加密推理：选择退出状态管理，同时仍可受益于高级推理能力。
  • 面向未来：为即将推出的模型做好兼容准备。
能力Chat Completions APIResponses API
文本生成
音频即将推出
视觉
结构化输出
函数调用
网络搜索
文件搜索
计算机使用
代码解释器
MCP
图像生成
推理摘要

示例

了解 Responses API 在特定场景下与 Chat Completions API 的具体对比。

Messages 与 Items

这两个 API 都能轻松生成模型输出。调用 Chat Completions 的输入和结果都是一个 Messages，而 Responses API 使用 Items。Item 是多种类型的联合体，代表了模型动作的各种可能性。 message 是一种 Item 类型， function_call or function_call_output。与 Chat Completions Message 中将多种关注点糅合在一个对象中不同，Items 彼此独立，能更好地代表模型上下文的基本单元。

此外，Chat Completions 可以通过 choices，使用 n 参数返回多个并行生成结果。在 Responses 中，我们移除了该参数，仅保留一次生成。

Chat Completions API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
from openai import OpenAI
client = OpenAI()

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

print(completion.choices[0].message.content)
Responses API
1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

response = client.responses.create(
model="gpt-5",
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "id": "chatcmpl-C9EDpkjH60VPPIB86j2zIhiR8kWiC",
  "object": "chat.completion",
  "created": 1756315657,
  "model": "gpt-5-2025-08-07",
  "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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "id": "resp_68af4030592c81938ec0a5fbab4a3e9f05438e46b5f69a3b",
  "object": "response",
  "created_at": 1756315696,
  "model": "gpt-5-2025-08-07",
  "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"
    }
  ],
  ...
}

数组的其他区别

  • 默认会存储响应。新账户默认会存储 Chat Completions 响应。要在任一 API 中禁用存储，请设置 store: false.
  • 推理 模型在 Responses API 中拥有更丰富的体验，具备 改进的工具使用的 Items 数组。从 GPT-5.4 开始，Chat Completions 不再支持通过 reasoning: none.
  • 结构化输出 API 形状有所不同。不同于 response_format进行工具调用，请使用 text.format （在 Responses 中）。了解更多信息，请参阅 结构化输出 guide.
  • 函数调用 API 形状有所不同，无论是请求中的函数配置，还是响应中返回的函数调用。请在 函数调用指南.
  • 中查看完整差异。Responses SDK 提供了一个 output_text 辅助工具，而 Chat Completions SDK 没有此工具。
  • 在 Chat Completions 中，对话状态必须手动管理。Responses API 兼容 对话 API 以实现持久对话，或者支持传入 previous_response_id 轻松地将多个响应串联起来。

从 Chat Completions 迁移

1. 更新生成端点

首先，将生成端点从 post /v1/chat/completions to post /v1/responses.

如果不使用函数或多模态输入，那么迁移就完成了！一个 API 到另一个 API 的简单消息输入是兼容的：

网页搜索工具
1
2
3
4
5
6
7
8
9
10
11
12
13
14
const context = [
  { role: 'system', content: 'You are a helpful assistant.' },
  { role: 'user', content: 'Hello!' }
];

const completion = await client.chat.completions.create({
  model: 'gpt-5',
  messages: messages
});

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

使用 Chat Completions 时，你需要创建一个消息数组，为每个角色指定不同的角色和内容。

从模型生成文本
1
2
3
4
5
6
7
8
9
10
11
import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

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

2. 更新条目定义

使用 Chat Completions 时，你需要创建一个消息数组，为每个角色指定不同的角色和内容。

从模型生成文本
1
2
3
4
5
6
7
8
9
10
11
import OpenAI from 'openai';
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

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

3. 更新多轮对话

如果你的应用中包含多轮对话，请更新你的上下文逻辑。

在 Chat Completions 中，你必须自行存储和管理上下文。

多轮对话
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
let messages = [
    { '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-5',
  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-5',
  messages
});

4. 决定何时使用有状态性

某些组织——例如具有零数据保留 (ZDR) 要求的组织——由于合规性或数据保留政策，无法以有状态方式使用 Responses API。为了支持这些情况，OpenAI 提供了加密推理项，允许你在保持工作流无状态的同时，仍能受益于推理项。

要禁用有状态性，但仍然利用推理功能：

API 随后将返回加密版本的推理 token，你可以在未来的请求中像传递常规推理项一样将其传回。对于 ZDR 组织，OpenAI 会自动强制执行 store=false。当请求包含 encrypted_content 时，它会在内存中被解密（绝不写入磁盘），用于生成下一个响应，然后被安全丢弃。任何新的推理 token 都会立即被加密并返回给你，确保不会持久化任何中间状态。

5. 更新函数定义

在 Chat Completions 和 Responses 之间，函数的定义方式有两个微小但值得注意的差异。

  1. 在 Chat Completions 中，函数使用外部标记的多态性来定义，而在 Responses 中，它们是内部标记的。
  2. 在 Chat Completions 中，函数默认为非严格模式，而在 Responses API 中，函数默认为 正在 严格模式。

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

Chat Completions API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
      "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",
            "unit"
          ]
        }
      }
  }
Responses API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
      "type": "function",
      "name": "get_weather",
      "description": "Determine weather in my location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
          },
        },
        "additionalProperties": false,
        "required": [
          "location",
          "unit"
        ]
      }
  }

遵循函数调用最佳实践

在 Responses 中，工具调用及其输出是两种不同类型的 Item，它们通过 call_id。请参阅 工具调用文档 以详细了解 Responses 中函数调用的工作原理。

6. 更新结构化输出定义

在 Responses API 中，定义结构化输出的位置已从 response_format to text.format:
结构化输出
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
const completion = await openai.chat.completions.create({
  model: "gpt-5",
  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
      }
    }
  },
  verbosity: "medium",
  reasoning_effort: "medium"
});

7. 升级到原生工具

如果你的应用在某些用例中能够受益于 OpenAI 的原生 工具，您可以将您的工具调用更新为开箱即用地使用 OpenAI 的工具。

在 Chat Completions 中，你无法原生使用 OpenAI 的工具，必须自行编写实现。

网页搜索工具
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
async function web_search(query) {
    const fetch = (await import('node-fetch')).default;
    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',
  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']
      }
    }
  ]
});

渐进式迁移

Responses API 是 Chat Completions API 的超集。Chat Completions API 也将继续获得支持。因此，如有需要，你可以渐进式地采用 Responses API。你可以将受益于改进后推理模型的用户流程迁移至 Responses API，同时将其他流程保留在 Chat Completions API，直到你准备好进行全面迁移。

作为最佳实践，我们鼓励所有用户迁移到 Responses API，以利用 OpenAI 提供的最新功能和改进。

Assistants API

根据开发者在 Assistants API 测试版的反馈，我们将多项关键改进融入了 Responses API，使其更加灵活、快速且易于使用。Responses API 代表了在 OpenAI 上构建智能体的未来方向。

Responses API 现在提供了类似 Assistant 和类似 Thread 的对象。如需了解更多信息，请参阅 迁移指南。截至 2025 年 8 月 26 日，我们正在弃用 Assistants API，停用日期为 2026 年 8 月 26 日。