OpenAI Responses API 如何区分 output_text 和完整输出项

调用 OpenAI Responses API 后，很多代码会在 response.output_text 和 response.output 之间犹豫。它们不是两次请求，也不是“新旧两套返回格式”：前者是 SDK 在支持时提供的便捷文本视图，后者是完整的输出项数组。只做页面展示、日志摘要或简单存档时优先用 output_text；需要识别消息、工具调用、推理项、状态或标注时，必须读取 output 并按类型判断。

先分清 Response、output 输出项和文本内容项

可以把返回值看成三层。最外层是 Response，它包含状态、模型、用量和 output；output 是一个数组，每个元素代表一种输出项；当输出项是消息时，它内部还有 content，其中的文本片段类型是 output_text。因此，output_text 这个名字既可能出现在 SDK 的便捷属性上，也会出现在消息内容片段的 type 字段里，二者不要混为一谈。

官方 API Reference 特别提醒，output 的长度与顺序依赖模型响应，不要直接取第一个元素再假定它是包含模型文本的消息。这个判断对启用工具、推理或其他输出项的请求尤其重要。

什么时候应该读取完整 output

如果目标只是把回答放进聊天气泡，output_text 足够直接。换成完整 output 的信号通常有三种：你要根据输出项类型分派处理；你要保存工具调用、函数参数或标注；你要在故障排查时解释“模型到底返回了哪些项”。这时不要只保存最终字符串，因为字符串无法表达每个输出项的类型、顺序和附加字段。

import OpenAI from "openai";

const client = new OpenAI();
const response = await client.responses.create({
  model: "gpt-5.2",
  input: "用一句话说明 Responses API 的输出层级"
});

// 展示场景：SDK 支持时，直接读取便捷文本属性。
console.log(response.output_text);

// 结构化场景：只从 message 的 output_text 内容片段提取文本。
const textParts = [];
for (const item of response.output ?? []) {
  if (item.type !== "message") continue;
  for (const part of item.content ?? []) {
    if (part.type === "output_text") textParts.push(part.text);
  }
}
console.log(textParts.join("\n"));

第二段遍历的价值不在于“多写几行代码”，而在于明确拒绝未知类型。将来请求加入工具时，output 可能同时包含消息和工具相关项；文本提取函数可以只收集消息文本，而路由器仍能读取原始数组处理其他类型。对于带文件引用或其他标注的文本，也应保留对应的内容片段对象，而不是只留下拼接后的字符串。

把选择写进适配层，避免业务代码猜结构

更稳妥的做法是让 API 适配层同时返回两个结果：一个给普通业务使用的文本字符串，一个供需要深入处理的原始响应。适配层内部只接受明确的 message 和 output_text 类型；业务页面不再散落 response.output[0] 之类的脆弱访问。

非流式请求完成后，可以把 status 一起记录下来，再决定是否展示文本。使用流式请求时则要改读事件，例如文本增量事件与输出项完成事件；不能在首个事件到来时就假设完整 response.output 已经存在。遇到 incomplete 或失败状态，也不要把空字符串误判成“模型没有回答”。

需要核对字段含义时，优先对照 OpenAI Responses API 官方 API Reference 的返回示例和输出项说明；SDK 版本变化时，保持“按类型读取”的原则比记住某个数组位置更可靠。

常见问题

output_text 为空时应该直接读 output[0] 吗？

不建议。先确认响应状态，再遍历所有输出项，只从类型为 message 的内容片段中提取 output_text。

只保存 output_text 会丢失什么？

会丢失输出项类型、工具调用信息、内容级标注以及调试所需的结构边界。只做展示时可以只存文本，做审计或二次处理时应保存原始响应或结构化子集。

流式和非流式读取方式一样吗？

不一样。非流式响应完成后可读取完整对象；流式场景应消费事件并自行累积文本，直到收到相应的完成事件。