For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

建议

开始使用

核心概念

SDK 与 CLI

资源

旧版 API

API Dashboard
试用 ChatGPT

迁移到 Responses API

Responses API 是我们新推出的 API 原语，在 Chat Completions 的基础上演进而来，让您的集成更简单，并提供强大的智能体原语。

我们仍支持 Chat Completions，但建议所有新项目使用 Responses。

关于 Responses API

Responses API 是一个统一接口，用于构建功能强大、具备智能体特性的应用。它包含：

Responses 的优势

与 Chat Completions 相比，Responses API 具有以下优势：

  • 表现更好：使用 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 在多轮交互之间维持状态，保留推理和工具上下文。
  • 灵活的输入：通过 input 传入字符串或消息列表；使用 instructions 提供系统级指令。
  • 加密推理：即使选择不保留状态，也能使用高级推理能力。
  • 面向未来：为即将推出的模型做好准备。
能力Chat Completions APIResponses API
文本生成
音频即将推出
视觉
结构化输出
函数调用
网页搜索
文件搜索
计算机使用
代码解释器
MCP
图像生成
推理摘要

示例

了解 Responses API 与 Chat Completions API 在具体场景中的区别。

消息与条目

这两个 API 都能让您轻松使用我们的模型生成输出。调用 Chat Completions 时，输入和返回结果都是 消息数组， 而 Responses API 使用 条目。条目是多种类型的联合，涵盖模型可能执行的各种操作。 message 是一种条目，function_call 和 function_call_output 也是如此。Chat Completions 的消息将多种不同用途的内容合并到一个对象中， 而各类条目彼此独立，能更好地表示模型上下文的基本单元。

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

Chat Completions API
from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-6-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-astra",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

Responses API 返回的响应在字段上略有不同。 您收到的不再是 message，而是一个带有类型和自身 id 的 response 对象。 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 结构有所不同。在 Responses 中，请使用 text.format 替代 response_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", content: "You are a helpful assistant." },
  { role: "user", content: "Hello!" },
];

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

const response = await client.responses.create({
  model: "gpt-6-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-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，可以是字符串，也可以是输入条目数组
系统或开发者指令顶层 instructions；如果需要保留现有对话记录，也可以使用兼容的消息条目
用户消息带有 role: "user" 的输入消息条目
助手消息response.output 中的输出消息条目；如果您手动管理状态，请在 input 中将其传回
工具或函数调用一个 function_call 输出条目
工具或函数结果一个通过 call_id 与调用关联的 function_call_output 输入条目
使用 n 生成多个结果Responses 不支持此功能；如果需要多个候选输出，请分别发送请求

如果您只需要最终文本，请使用 SDK 提供的 output_text 辅助功能。如果您的流程涉及推理、工具或多模态输出，请遍历 response.output，并根据各条目的 type 进行处理。

3. 更新多轮对话

如果您的应用中有多轮对话，请更新上下文处理逻辑。Responses 提供三种常见的状态管理方式：

  • 如果您希望 OpenAI 管理先前响应的上下文，请使用 previous_response_id。每次请求都应重新发送固定的 instructions，因为 previous_response_id 不会沿用上一条响应的顶层 instructions。
  • 如果您需要自行管理或裁剪上下文，请在下一次请求中传回先前的 output 条目。
  • 如果您需要持久化的对话对象，请使用 Conversations API。

使用 Chat Completions 时，您需要存储对话记录， 并在每次请求中发送累积的 messages 数组。
多轮对话
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-6-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-astra",
  messages,
});

即使使用 previous_response_id，响应链中先前响应的所有输入 Token 仍会在 API 中按输入 Token 计费。

4. 确定何时使用有状态方式

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

某些组织（例如有零数据保留（ZDR）要求的组织）受合规要求或数据保留政策限制，无法以有状态方式使用 Responses API。为支持这些情况，OpenAI 提供了加密推理条目，让您在保持工作流程无状态的同时，仍能利用推理条目。

要在禁用有状态方式的同时继续使用推理功能，请执行以下操作：

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

随后，API 会返回加密后的推理 Token，您可以像处理普通推理条目一样，在后续请求中将其传回。 对于 ZDR 组织，OpenAI 会自动强制使用 store: false。当请求包含 encrypted_content 时，其内容会在内存中解密，用于生成下一条响应，然后被安全丢弃。任何新生成的推理 Token 都会立即加密并返回给您，确保不会持久化存储任何中间状态。

5. 更新函数定义和输出

Chat Completions 和 Responses 的函数定义方式有两处细微但需要注意的差异。

  1. 在 Chat Completions 中，函数定义采用外部标记方式；在 Responses 中，则采用内部标记方式。
  2. 在 Chat Completions 中，函数默认使用非严格模式。在 Responses 中，省略 strict 会尝试启用严格模式；如果无法使模式定义满足兼容性要求，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-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 进行分支处理，并处理您的 UI 或编排层所需的事件。

对于文本流式传输，请监听以下事件：

  • 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，因为 GPT-6 Astra 需要通过 Responses API 进行工具调用。
网页搜索工具
async function web_search(query) {
  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",
  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。