Responses API
OpenAI 面向推理、多模态输入、工具调用和多轮状态的新一代统一响应接口。
#type / resource
#status / growing
#tech / ai
#resource / openai
#interface / api
Responses API
核心模型
Responses API 把一次模型运行表示为结构化的 response。输入与输出不再只是一串 role/content 消息：输出可以包含文本消息、推理项、函数调用、托管工具调用及其结果等不同 item。
这种对象模型的价值在于：应用不必把所有能力压缩进聊天文本，而能明确处理模型输出、工具协议、状态续接和结构化结果。
典型执行循环
- 应用提交 instructions、input、model 和可用 tools。
- 模型直接返回结果，或产生一个/多个工具调用 item。
- 应用验证参数、执行自管函数或接受托管工具结果。
- 应用把工具输出与正确的 call ID 关联后继续 response。
- 达到终止条件后读取最终消息，并记录 usage、错误和 trace 信息。
状态策略
- 显式历史：应用保存必要的 input/output items 并在后续请求重放，控制力强。
previous_response_id：让后续响应引用先前响应，简化多轮续接。- 无状态或受限保留：对隐私、ZDR 或合规要求较高的工作流，应按官方说明选择存储配置并保留必要的加密推理项。
状态续接不是业务事实存储。用户资料、审批状态、订单结果和知识库版本仍应存放在应用自己的数据库或审计日志中。
工具边界
工具描述要写清输入、返回结构与错误语义；应用必须执行权限检查、参数校验、超时、幂等和审计。模型提出调用不等于调用已经被授权，尤其是写入、支付、发送和删除操作。
最小实现骨架
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="<从官方模型目录选择>",
instructions="只根据已提供证据回答。",
input="总结这份材料。",
)
print(response.output_text)示例故意不固定模型版本。生产代码应通过配置选择模型，并用评估集验证升级。
常见误区
- 只读取第一个 output item，遗漏工具调用或其他结构化输出。
- 把 response ID 当作永久数据库主键或业务状态唯一来源。
- 对副作用工具无限自动重试，导致重复写入。
- 迁移接口时只改 URL，不重新验证提示词、输出解析和工具循环。
相关笔记
- responses-api-vs-chat-completions-api
- openai-api-tools-mcp-and-hosted-tools
- openai-agent-evaluation-and-tracing
- tool-calling