OpenAI Responses API 的 output、Output Item、Message Content、output_text、Refusal、Annotations 和 Reasoning Item 有什么区别？

名称 所在层级 主要作用 常见误区

-----------

Response 顶层对象 表示一次响应及其状态、ID、错误和输出 看到 HTTP 成功就认定生成已完整完成

output Response 内的数组 按序容纳 message、reasoning、tool call 等 Output Item 假定 output[0] 必然是最终文本消息

Output Item output 数组元素 表示一次消息、推理项目或工具调用等语义单元 不检查 type 就按 message 解析

Message Content message 的 content 数组元素 承载输出文本或拒绝等内容部件 假定 content[0].text 永远存在

outputtext 内容部件 Message Content 的一种 保存模型输出文本，并可附带 annotations 等信息 与 SDK 顶层便捷属性混为一谈

SDK response.outputtext 客户端便捷属性 聚合响应中的文本输出，方便读取 当成服务端原始 JSON 的唯一权威结构

Refusal Message Content 的一种 明确表达模型拒绝提供某项内容 当成空文本、网络错误或 JSON 解析错误

Annotations 某段输出文本的附属信息 描述引用等与文本位置相关的标注 脱离所属文本单独保存，导致位置失效

Reasoning Item Output Item 的一种 表示推理模型返回的推理相关项目 当成面向用户的答案，或尝试提取隐藏思维过程

Response 是最外层容器。应用应先读取响应的标识、状态以及错误或不完整信息，再决定是否消费 output。不要把 HTTP 200 与“已经获得完整最终答案”画等号。异步或后台执行可能仍处于处理中；响应也可能以不完整状态结束，并在 incompletedetails 中提供原因。顶层 error 则表示响应级错误信息。