迁移到 Responses API

Responses API 是我们全新的 API 基础原语，是 Chat Completions 的演进版本，为你的集成带来了更简洁的接口和强大的代理能力。

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

关于 Responses API

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

内置工具：网页搜索、文件搜索、计算机使用、代码解释器、远程 MCP
无缝多轮交互：可以传入之前的响应，获得更高准确度的推理结果
原生多模态支持：文本与图像

Responses API 的优势

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

更好的性能：使用推理模型（如 GPT-5）搭配 Responses API，模型智能水平优于 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 API	Responses API
文本生成	✓	✓
音频	✓	即将推出
视觉	✓	✓
结构化输出	✓	✓
函数调用	✓	✓
网页搜索	✗	✓
文件搜索	✗	✓
计算机使用	✗	✓
代码解释器	✗	✓
MCP	✗	✓
图像生成	✗	✓
推理摘要	✗	✓

示例

Messages vs. Items

两个 API 都可以方便地从模型生成输出。Chat Completions 的输入和结果是一个 Messages 数组，而 Responses API 使用 Items。

Item 是一个联合类型，代表模型可能执行的各种操作。message 是 Item 的一种类型，function_call 或 function_call_output 也是。与 Chat Completions 的 Message 不同（一个对象里混合了多种关注点），Items 彼此独立，更好地代表了模型上下文的基本单元。

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

当你从 Responses API 收到响应时，字段会略有不同。你不再收到 message，而是收到一个带有自己 id 的类型化 response 对象。Responses 默认会被存储。Chat Completions 对新账户也默认存储。如果要禁用存储，在任一 API 中设置 store: false。

其他差异

Responses 默认存储。Chat Completions 对新账户默认存储。要禁用存储，设置 store: false。
推理模型在 Responses API 中有更丰富的体验，包括改进的工具使用。从 GPT-5.4 开始，Chat Completions 中设置 reasoning: none 时不支持工具调用。
Structured Outputs 的 API 形状不同。在 Responses 中使用 text.format 而不是 response_format。详见结构化输出指南。
函数调用的 API 形状不同，包括请求中的函数配置和响应中返回的函数调用。详见函数调用指南。
Responses SDK 有一个 output_text 辅助属性，Chat Completions SDK 没有。
在 Chat Completions 中，对话状态必须手动管理。Responses API 兼容 Conversations API 用于持久化对话，或者可以传入 previous_response_id 来轻松串联多个 Response。

从 Chat Completions 迁移

1. 更新生成端点

首先把生成端点从 POST /v1/chat/completions 更新为 POST /v1/responses。

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

bash

INPUT='[
  { "role": "system", "content": "You are a helpful assistant." },
  { "role": "user", "content": "Hello!" }
]'

curl -s https://xikapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XIKAPI_API_KEY" \
  -d "{
    \"model\": \"gpt-5\",
    \"messages\": $INPUT
  }"

curl -s https://xikapi.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XIKAPI_API_KEY" \
  -d "{
    \"model\": \"gpt-5\",
    \"input\": $INPUT
  }"

javascript

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: context
});

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

python

context = [
  { "role": "system", "content": "You are a helpful assistant." },
  { "role": "user", "content": "Hello!" }
]

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

response = client.responses.create(
  model="gpt-5",
  input=context
)

在 Responses 中，你还可以在顶层分离 instructions 和 input，语义更清晰：

javascript

const response = await client.responses.create({
  model: 'gpt-5',
  instructions: 'You are a helpful assistant.',
  input: 'Hello!'
});

console.log(response.output_text);

python

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

2. 更新 item 定义

Chat Completions 使用 messages 数组，Responses 使用 items。两者结构类似，但 Responses 的语义更清晰。

3. 更新多轮对话

如果你的应用有多轮对话，需要更新上下文管理逻辑。

Chat Completions 方式

在 Chat Completions 中，你需要自己存储和管理上下文：

javascript

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 });

python

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 方式

在 Responses 中，你可以把上一个响应的 output 追加到下一个请求的 input 中：

python

context = [
    { "role": "user", "content": "What is the capital of France?" }
]
res1 = client.responses.create(model="gpt-5", input=context)

# Append the first response's output to context
context += res1.output

# Add the next user message
context += [{ "role": "user", "content": "And its population?" }]

res2 = client.responses.create(model="gpt-5", input=context)

javascript

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

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

// Append the first response's output to context
context = context.concat(res1.output);

// Add the next user message
context.push({ role: "user", content: "And its population?" });

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

更简单的方式是使用 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
});

python

res1 = client.responses.create(
    model="gpt-5",
    input="What is the capital of France?",
    store=True
)

res2 = client.responses.create(
    model="gpt-5",
    input="And its population?",
    previous_response_id=res1.id,
    store=True
)

4. 决定是否使用有状态模式

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

要禁用有状态模式但仍利用推理：

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

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

5. 更新函数定义

Chat Completions 与 Responses 在函数定义上有两个小但重要的差异：

在 Chat Completions 中，函数使用外部标记多态（externally tagged polymorphism）定义；在 Responses 中，使用内部标记（internally-tagged）。
在 Chat Completions 中，函数默认是非严格模式；在 Responses API 中，函数默认是严格模式。

遵循函数调用最佳实践

在 Responses 中，工具调用和它们的输出是两种不同类型的 Item，通过 call_id 关联。详见工具调用文档。

6. 更新 Structured Outputs 定义

在 Responses API 中，结构化输出的定义从 response_format 移到了 text.format：

Chat Completions 方式

python

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
      }
    }
  }
)

Responses 方式

python

response = client.responses.create(
  model="gpt-5",
  input="Jane, 54 years old",
  text={
    "format": {
      "type": "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
      }
    }
  }
)

7. 升级到原生工具

如果你的应用有适合使用 OpenAI 原生工具的场景，可以直接使用内置工具，无需自己实现。

Chat Completions 方式（需要自己实现）

python

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

Responses 方式（直接使用内置工具）

python

answer = client.responses.create(
    model="gpt-5.5",
    input="Who is the current president of France?",
    tools=[{"type": "web_search"}]
)

print(answer.output_text)

javascript

const answer = await client.responses.create({
    model: 'gpt-5.5',
    input: 'Who is the current president of France?',
    tools: [{ type: 'web_search' }]
});

console.log(answer.output_text);

bash

curl https://xikapi.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XIKAPI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "input": "Who is the current president of France?",
    "tools": [{"type": "web_search"}]
  }'

渐进式迁移

Responses API 是 Chat Completions API 的超集。Chat Completions API 也将继续受支持。因此，你可以按需渐进式地采用 Responses API。

你可以先把那些能从改进推理模型中受益的用户流程迁移到 Responses API，同时让其他流程继续使用 Chat Completions API，直到你准备好全面迁移。

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

Assistants API

基于 Assistants API beta 阶段的开发者反馈，我们已将关键改进整合到 Responses API 中，使其更灵活、更快速、更易用。Responses API 代表了在 OpenAI 上构建代理的未来方向。

我们现在在 Responses API 中提供了类似 Assistant 和 Thread 的对象。详见迁移指南。
自 2025 年 8 月 26 日起，我们将弃用 Assistants API，日落日期为 2026 年 8 月 26 日。

迁移到 Responses API ​

关于 Responses API ​

Responses API 的优势 ​

示例 ​

Messages vs. Items ​

其他差异 ​

从 Chat Completions 迁移 ​

1. 更新生成端点 ​

2. 更新 item 定义 ​

3. 更新多轮对话 ​

Chat Completions 方式 ​

Responses 方式 ​

4. 决定是否使用有状态模式 ​

5. 更新函数定义 ​

遵循函数调用最佳实践 ​

6. 更新 Structured Outputs 定义 ​

Chat Completions 方式 ​

Responses 方式 ​

7. 升级到原生工具 ​

Chat Completions 方式（需要自己实现） ​

Responses 方式（直接使用内置工具） ​

渐进式迁移 ​

Assistants API ​

迁移到 Responses API

关于 Responses API

Responses API 的优势

示例

Messages vs. Items

其他差异

从 Chat Completions 迁移

1. 更新生成端点

2. 更新 item 定义

3. 更新多轮对话

Chat Completions 方式

Responses 方式

4. 决定是否使用有状态模式

5. 更新函数定义

遵循函数调用最佳实践

6. 更新 Structured Outputs 定义

Chat Completions 方式

Responses 方式

7. 升级到原生工具

Chat Completions 方式（需要自己实现）

Responses 方式（直接使用内置工具）

渐进式迁移

Assistants API