OpenAI API 流式输出（streaming）怎么写：stream=True、response.output_text.delta 事件、Python 和 Node 示例

本文根据 OpenAI 官方《Streaming API responses》和 Quickstart 整理，资料核对于 2026-11-05。代码里的模型名取自官方当天示例，请以官方模型页为准。本站（bigolab.com）不是 OpenAI 官方网站。API 是按用量计费的独立服务，与 ChatGPT 订阅分开计算，Key 的获取见 /guides/openai-api-key。

适用于谁

• 用 OpenAI API 做聊天界面、写作工具，希望文字边生成边显示的开发者；
• 已经能发出第一个请求（见 /guides/openai-api-python-quickstart），想了解流式事件到底是什么的人；
• 用 Node.js / TypeScript 的前端或全栈开发者。

结论先说

1. 默认不是流式的。 官方说，普通请求会等整个输出生成完才一次性返回，输出长的时候要等。
2. 流式的写法：在 Responses 请求里加 stream=True（Node 里是 stream: true），得到的不是一个结果，而是一串事件。
3. 事件是带类型的，用 event.type 区分。写文本时常看四个：response.created、response.output_text.delta、response.completed、error。
4. 文字增量在 response.output_text.delta 里，用 event.delta 取。
5. 流式让内容审核更难。 官方明确提醒，生产应用里流式输出会让部分内容更难评估，审核分数也要等完整输出生成后才有。

图：本站根据 OpenAI 官方《Streaming API responses》 整理的示意图

一、事件长什么样

官方说，Responses API 用语义事件来流式返回，每种事件有预先定义的结构。其中有的只出现一次，有的会随着生成多次出现：

• response.created：响应开始创建，出现一次；
• response.output_text.delta：一小段新文字，出现很多次；
• response.completed：整个响应完成，出现一次；
• error：出错。

完整事件列表见官方 API 参考里的 streaming 部分，正文不全部列出。

二、Python 示例

先安装并设置密钥（Windows 的设置方式见 /guides/openai-api-key）：

pip install openai

python
from openai import OpenAI

client = OpenAI()  # 从环境变量 OPENAI_API_KEY 读取密钥

stream = client.responses.create(
    model="gpt-6-astra",  # 以官方模型页当天为准
    input="用三句话介绍什么是流式输出。",
    stream=True,
)

full_text = ""
for event in stream:
    if event.type == "response.output_text.delta":
        full_text += event.delta
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\n--- 完成 ---")
    elif event.type == "error":
        print("\n出错：", event.message)

print("完整文本长度：", len(full_text))

flush=True 让文字立即显示在终端里。full_text 把增量拼起来，方便流结束后保存或再处理。

三、Node.js 示例

新建一个 stream.mjs 文件（.mjs 可以直接使用 import 和顶层 await）：

npm install openai

javascript
import OpenAI from "openai";

const client = new OpenAI(); // 从环境变量 OPENAI_API_KEY 读取密钥

const stream = await client.responses.create({
  model: "gpt-6-astra", // 以官方模型页当天为准
  input: "用三句话介绍什么是流式输出。",
  stream: true,
});

let fullText = "";
for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    fullText += event.delta;
    process.stdout.write(event.delta);
  } else if (event.type === "response.completed") {
    console.log("\n--- 完成 ---");
  } else if (event.type === "error") {
    console.error(event.message);
  }
}
console.log("完整文本长度：", fullText.length);

运行：node stream.mjs。官方示例里的判断结构与上面一致。

四、常见的几个坑

图：本站根据 OpenAI 官方《Streaming API responses》 整理的示意图，排查表为本站补充

• 什么也没显示：检查有没有真的加 stream=True；再检查有没有只打印 response.completed 之类的事件，漏掉了 response.output_text.delta；
• 文字还是一次性出来：终端没有立即刷新（Python 要 flush=True），或者中间的代理、网关把响应缓冲了；
• 中途断掉：把已收到的文本先保存，再按业务决定要不要重试。重试会重新计费，429 等限流问题见 /guides/openai-api-429-error；
• 要保存完整答案：像示例那样拼接增量，或者在 response.completed 事件里读完整响应；
• 想知道用了多少 token：用量见 /guides/openai-api-pricing-billing，价格以官方页面当前显示为准。

五、要给用户看，怎么转给浏览器

官方流式页讲的是 API 和服务器之间的流。网页前端怎么拿到，官方这一页没有展开。本站的一般性建议：密钥只放在你自己的服务器上，不要写进网页或手机 App；服务器收到 OpenAI 的事件后，用你自己的方式（例如服务器发送事件或 WebSocket）转给前端，只转发文字增量就够了。

官方提到的另外两个方向：想要持久的 WebSocket 连接并用 previous_response_id 增量输入，看官方的 Responses WebSocket 模式；流式的函数调用和结构化输出，官方另有专门的指南。

六、关于审核风险

官方在流式页专门有一节“Moderation risk”：生产应用里流式输出会让内容审核更困难，因为部分输出更难评估，这可能影响获批的使用。如果在生成请求时请求审核分数，分数会在完整输出可用后才到，不会跟着增量事件一起出现。

所以做面向公众的产品时，要把审核放进设计里，比如先在服务器收齐、检查，再决定怎么展示，具体做法以官方审核指南为准。

什么时候值得用流式

• 适合：聊天界面、写作助手、需要让用户尽早看到开头的长回答。官方的理由就是：模型还在继续生成时，你已经可以开始显示或处理开头部分；
• 不一定需要：后台批处理、只需要最终结果的脚本、要先整体校验再使用的输出。这些场景用普通请求更简单，代码也更短；
• 需要先想清楚：出错后怎么办。非流式请求要么成功要么失败，流式请求可能已经给用户显示了一半文字才断开，界面上要有“生成中断、重试”的处理，这是本站的一般性建议。

常见问题

Q：旧资料里的 Chat Completions 流式写法还能用吗？

官方流式页对 Chat Completions 单独有一段：流式返回的是 chunk.choices[0].delta，取的是 delta 里的内容，和 Responses 的 event.delta 不是一回事。新项目建议优先用 Responses，两者区别见 /guides/openai-responses-api。

Q：流式会比非流式贵吗？

官方流式页没有这样说明，计费看的是用量，以官方价格页为准，见 /guides/openai-api-price-official-table。

Q：模型名报错怎么办？

示例模型名会更新，先到官方模型页确认你的账号可用的模型。

参考资料

• OpenAI 官方：Streaming API responses — https://platform.openai.com/docs/guides/streaming-responses
• OpenAI 官方：Quickstart — https://developers.openai.com/api/docs/quickstart