迁移到 Responses API

响应 API 是我们新的 API 原语，是聊天完成的演变，为您的集成带来了更多的简单性和强大的代理原语。

注意：虽然聊天完成功能仍受支持，但建议将“响应”用于所有新项目。

关于响应 API

Responses API 是一个统一的接口，用于构建功能强大的类似代理的应用程序。它包含：

内置工具，如网络搜索、文件搜索、计算机使用、代码解释器和远程 MCP。
无缝的多轮交互，允许您传递以前的响应以获得更准确的推理结果。
对文本和图像的原生多模态支持。

响应优势

与聊天完成相比，响应 API 包含多项优势：

更好的性能：与聊天完成相比，将推理模型（如 GPT-5）与响应一起使用将产生更好的模型智能。我们的内部评估显示，在相同的提示和设置下，SWE-bench 提高了 3%。
默认代理：响应 API 是一个代理循环，允许模型在一个 API 请求的范围内调用多个工具，例如 web_search、image_generation、file_search、code_interpreter、远程 MCP 服务器以及您自己的自定义函数。
降低成本：由于缓存利用率提高，成本降低（与内部测试中的聊天完成相比，提高了 40% 到 80%）。
有状态上下文：使用 store: true 逐个回合维护状态，逐个回合保留推理和工具上下文。
灵活的输入：传递带有输入的字符串或消息列表；使用说明获取系统级指导。
加密推理：选择退出状态，同时仍受益于高级推理。
面向未来：面向未来的型号。

功能对比

Capabilities	Chat Completions API	Responses API
Text generation	✅	✅
Audio	✅	即将推出
Vision	✅	✅
Structured Outputs	✅	✅
Function calling	✅	✅
Web search	✅	✅
File search	❌	✅
Computer use	❌	✅
Code interpreter	❌	✅
MCP	❌	✅
Image generation	❌	✅
Reasoning summaries	❌	✅

Chat Completions API 和 Responses API 都可以轻松生成模型输出。Chat Completions 的输入和结果是一个 Messages 数组，而 Responses API 使用 Items。Item 是多种类型的联合体，代表模型操作的多种可能性。message 是一种 Item 类型，function_call 或 function_call_output 也是。

Chat Completions API 示例

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 示例

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 时，返回的字段略有不同。您将收到一个类型化的 response 对象，而不是 message，并且每个响应都有自己的 id。响应默认存储，而聊天完成默认对新账户存储。要在使用任何 API 时禁用存储，请设置 store: false。

从聊天完成迁移

1. 更新生成端点

将生成端点从 post /v1/chat/completions 更新为 post /v1/responses。

如果您没有使用函数或多模态输入，那么您已经完成了！简单的消息输入在两个 API 之间是兼容的：

# Chat Completions
completion = client.chat.completions.create(
  model="gpt-5",
  messages=[
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
  ]
)

# Responses
response = client.responses.create(
  model="gpt-5",
  input=[
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
  ]
)

2. 更新项目定义

在 Responses API 中，您可以在顶层分离指令和输入。API 形状与 Chat Completions 类似，但语义更清晰。

# Responses
response = client.responses.create(
  model="gpt-5",
  instructions="You are a helpful assistant.",
  input="Hello!"
)

3. 更新多轮对话

如果您的应用程序中有多轮对话，请更新您的上下文逻辑。

Chat Completions

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
]

res1 = client.chat.completions.create(model="gpt-5", messages=messages)

messages += [res1.choices[0].message]
messages += [{"role": "user", "content": "And its population?"}]

res2 = client.chat.completions.create(model="gpt-5", messages=messages)

Responses

以下是您提供的内容整理成 Markdown 格式，并保持了代码示例和逻辑结构：

多轮对话

使用上下文传递

在 Responses API 中，模式类似于 Chat Completions，您可以将一个响应的输出传递到另一个响应的输入中。

JavaScript 示例

let context = [
    { "role": "user", "content": "What is the capital of France?" }
];

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

// 将第一个响应的输出附加到上下文
context = [...context, ...res1.output];

// 添加下一个用户消息
context.push({ "role": "user", "content": "And its population?" });

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

使用 `previous_response_id`

为了简化多轮对话，您可以通过传递其 id 来简单地引用之前响应的输入和输出。使用 previous_response_id 可以形成相互构建的响应链或在历史记录中创建分支。

JavaScript 示例

const res1 = await client.responses.create({
    model: "gpt-5",
    input: "What is the capital of France?",
    store: true
});

const res2 = await client.responses.create({
    model: "gpt-5",
    input: "And its population?",
    previous_response_id: res1.id,
    store: true
});

决定何时使用有状态性

由于合规性或数据保留策略，某些组织（例如具有 零数据保留（ZDR） 要求的组织）无法以有状态方式使用 Responses API。为了支持这些情况，OpenAI 提供了加密的推理项目，使您能够保持工作流程无状态，同时仍能从推理项目中受益。

禁用有状态性

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

在 store 字段中设置 store: false
添加到 ["reasoning.encrypted_content"] 的 contains 字段

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

更新函数定义

Chat Completions 和 Responses 之间的函数定义方式有两个细微但显著的差异：

在 Chat Completions 中，函数是使用外部标记的多态性定义的，而在 Responses 中，它们是内部标记的。
在 Chat Completions 中，函数默认为不严格，而在 Responses API 中，函数默认为严格。

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",
        "unit"
      ]
    }
  }
}

Responses API

{
  "type": "function",
  "name": "get_weather",
  "description": "Determine weather in my location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string"
      }
    },
    "additionalProperties": false,
    "required": [
      "location",
      "unit"
    ]
  }
}

OpenAI 函数调用与 Responses API 最佳实践

1. 工具调用与输出

在响应中，工具调用 与其输出是两种不同类型的项。
它们使用 call_id 进行关联。
更多细节请参考官方的 工具调用文档。

2. 更新结构化输出定义

在 Responses API 中，结构化输出的定义位置有所变化：

旧版：response_format
新版：text.format

示例代码（Python）

from openai import OpenAI
client = OpenAI()

response = client.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"
)

3. 升级到本机工具

如果应用场景可以从 OpenAI 本机工具 中受益，推荐更新工具调用以使用开箱即用的工具。

Chat Completions 限制

Chat Completions 无法直接使用 OpenAI 的本机工具。
必须编写并注册 自定义工具。

示例：自定义网络搜索工具

import requests

def web_search(query):
    r = requests.get(f"https://api.example.com/search?q={query}")
    return r.json().get("results", [])

completion = 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"]
            }
        }
    ]
)

4. 增量迁移策略

Responses API 是 Chat Completions API 的超集。
Chat Completions API 将继续受支持。
可以选择 增量迁移：
- 将受益于 改进推理模型 的用户流迁移到 Responses API。
- 其他流继续保留在 Chat Completions API 上，直到准备好完全迁移。

最佳实践：建议所有用户迁移到 Responses API，以利用最新功能和改进。

5. Assistants API 弃用计划

根据 Assistants API Beta 的开发者反馈，Responses API 进行了关键改进：
- 更灵活
- 更快
- 更易用
Responses API 是在 OpenAI 上构建代理的未来方向。

时间表

2025 年 8 月 26 日起：开始弃用 Assistants API
2026 年 8 月 26 日：Assistants API 停用

在 Responses API 中，现在提供了 类似 Assistant 和 类似 Thread 的对象。更多细节可查阅官方的迁移指南。

迁移到 Responses API

功能对比

Messages vs. Items

Chat Completions API 示例

Responses API 示例

返回对象的差异

1. 更新生成端点

2. 更新项目定义

3. 更新多轮对话

Chat Completions

Responses

使用上下文传递

JavaScript 示例

使用 previous_response_id

JavaScript 示例

禁用有状态性

Chat Completions API

Responses API

OpenAI 函数调用与 Responses API 最佳实践

示例代码（Python）

Chat Completions 限制

示例：自定义网络搜索工具

时间表

使用 `previous_response_id`