Responses API 中文指南

更新时间：2026-08-12

导读

如果你今天从零集成 OpenAI 的对话能力，官方 文档 指向 Responses API 而非 legacy Chat Completions。Responses 统一文本 / 多模态输入、工具调用与对话状态，是新功能（托管 web search、file search 等）的默认落点。字段名、工具列表、model ID、单价以 Responses 指南 与 定价页 为准——API 仍在快速演进，请用配置项管理 model 与 schema 版本。

定位：Chat Completions 的继任路径

OpenAI 将 Responses 作为新集成首选；Chat Completions 进入维护期，新能力优先 Responses。Assistants（Thread / Run）亦向 Responses + Agents SDK 收敛。

能力	Chat Completions	Responses（推荐）
文档主推	否	是
输入形态	messages[]	instructions + input
输出形态	choices[].message	output[] + output_text
多模态	支持	同端点，见 Vision
对话状态	客户端拼 history	previous_response_id 链式引用
托管工具	有限	web search 等（视文档）

实践结论： 2026 新项目默认 Responses；存量 Completions 计划 shadow 迁移并保留回滚。

请求—响应模型

POST /v1/responses
  model + instructions + input (+ tools + previous_response_id)
    → output[]: message | function_call | …
    → usage + response.id

字段	开发者用法
instructions	长期 system 行为、格式约束
input	字符串或 items（文本 / 图片 / 工具结果）
tools	自定义 JSON Schema + 平台托管工具
store	true 时可后续用 id 引用，注意 retention 策略
stream	SSE，改善首 token 体验

最小可运行示例

from openai import OpenAI

client = OpenAI()
resp = client.responses.create(
    model="gpt-4o",  # 以 Models 页当前 ID 为准
    instructions="你是简洁的中文技术助手，回答不超过三句话。",
    input="Responses API 和 Chat Completions 最大区别是什么？",
)
print(resp.output_text)
print(resp.usage)

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","instructions":"You are helpful.","input":"Hi"}'

gpt-4o 仅为占位；替换为 Models 页当前 ID。

字段映射速查（Completions → Responses）

Chat Completions	Responses
messages[0] role=system	instructions
messages[-1] role=user	input 或 input items
choices[0].message.content	output_text
tool_calls + 手搓循环	output 中 function_call + 回传 tool result
response_format: json_object	Responses JSON schema / text.format

迁移时在 Playground 并排对照同一条业务请求，比逐字段手工翻译更可靠。

工具调用：自定义与托管

自定义 function： 声明 tools → 模型返回 function_call → 服务端执行 → 结果作为新 input item 再次 create → 直至最终文本。

托管工具： 文档可能提供 web search、file search、code interpreter；启用前确认数据出境、权限与附加计费（可能高于纯 token）。

多 Agent 编排见 Agents SDK 指南；底层仍调 Responses。

流式与幂等

stream = client.responses.create(
    model="gpt-4o",
    input="用四行诗描述 API 设计",
    stream=True,
)
for event in stream:
    pass  # 事件类型以 SDK 为准

带副作用的工具（写库、发邮件、扣款）必须幂等（idempotency key），防止 SSE 断线重试重复执行。

Shadow 迁移四步

1. 选代表性生产请求，Playground 转为 Responses JSON
2. Shadow 双跑：Completions 与 Responses 并行，对比质量、token、延迟
3. 读流量切 Responses，Completions 保留 2–4 周回滚开关
4. 订阅 Changelog 跟踪 deprecations

Assistants 存量见 Assistants 指南。

常见组合

场景	栈
RAG	Embeddings 检索 + Responses 生成
票据 OCR	Vision input items + JSON schema
长对话	previous_response_id 或定期摘要截断 history

生产清单

• Key 仅服务端；timeout + 429 指数退避
• 记录 response.id 便于 support 工单
• 工具 allowlist + 参数校验，防 prompt injection
• 监控 token + 托管工具附加费
• 按组织策略配置 store 与数据 retention

常见问题

Chat Completions 会立刻下线吗？

以官方 Changelog 为准；通常有过渡期，新能力优先 Responses。

只用 output_text 够吗？

纯文本问答够；解析 tool calls 或多段 output 需遍历 output[]。

同 model 下 Responses 更贵吗？

token 单价一般一致；托管工具可能另计费——用 shadow 对比总账单。

不用 SDK 可以吗？

可以；REST 字段以 API reference 为准，SDK 通常更快跟进新参数。

新 agent 选 Responses 还是 Assistants？

新需求优先 Responses + Agents SDK；勿在新项目重复投资 Thread / Run 模型。

官方资源

• Responses API 指南
• API Reference: Responses
• OpenAI Platform
• API 定价

下一步阅读

• Agents SDK 与 Apps SDK 入门
• OpenAI API 快速入门
• Assistants API 开发指南
• Embeddings（嵌入）

行动路径

今天：非流式 Responses 跑通，打印 output_text 与 usage。明天：实现一条自定义 function 的完整 tool 循环。本周：选一条 Completions 流量 shadow 双跑，输出迁移时间表。