流式输出

流式输出会在模型生成过程中分批返回事件，适合聊天界面和需要尽快显示首段内容的程序。

模型占位符

把示例中的 YOUR_MODEL_ID 替换为 DuckMans 后台中当前 Key 和分组实际可用的模型 ID。还要确认该模型、分组和所选 Endpoint 路径支持流式返回。

示意图：解析器按事件边界读取，而不是按网络数据块直接解析；可复制的地址、命令和代码仍以正文为准。

Chat Completions 流式请求

下面使用完整请求地址 https://duckmans.com/v1/chat/completions。curl -N 会关闭输出缓冲，便于立即看到数据块：

old_stty=$(stty -g)
trap 'stty "$old_stty"' EXIT INT TERM
printf "DuckMans API Key: "
stty -echo
IFS= read -r DUCKMANS_API_KEY
stty "$old_stty"
trap - EXIT INT TERM
printf '\n'
export DUCKMANS_API_KEY

curl -N -sS https://duckmans.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DUCKMANS_API_KEY" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "用三句话介绍 DuckMans API"}
    ],
    "stream": true
  }'

Responses 流式请求

只有在当前客户端、Key 分组和渠道明确支持 Responses 时，才使用完整请求地址 https://duckmans.com/v1/responses：

curl -N -sS https://duckmans.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DUCKMANS_API_KEY" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "input": "用三句话介绍 DuckMans API",
    "stream": true
  }'

Responses 是否可用需以客户端和 Key 分组的实际支持为准。如果 /responses 不受支持，而客户端允许切换协议，请改用 Chat Completions。

示意图：Chat 以 data [DONE] 结束，Responses 按事件名和数据处理；可复制的地址、命令和代码仍以正文为准。

解析原则

流式响应通常使用 Server-Sent Events（SSE）。实现解析器时应：

1. 按事件边界逐条读取，不要等待连接关闭后再一次性解析。
2. 能处理一个网络数据块中包含多个事件，或一个事件被拆成多个网络数据块。
3. 忽略空行，并按所选 Endpoint 路径的事件格式提取增量文本。
4. 正确处理完成事件、错误事件和连接中断。
5. 不要把 Responses 事件当成 Chat Completions 的 choices[].delta；两种协议的流结构不同。

优先使用支持对应协议的 SDK，它会代为处理事件边界。若必须自行解析 SSE，不要用简单的逐块 JSON.parse 代替事件解析器。

常见问题

终端很久才一次性显示

确认请求使用 curl -N。在自己的服务中，还要检查反向代理、Web 框架或 CDN 是否对响应做了缓冲。

返回成功但页面没有文字

确认前端解析的是当前 Endpoint 路径的流格式。Chat Completions 与 Responses 的增量字段不同。

中途断开

记录请求是否已经向用户输出内容。只对尚未产生副作用、且可以安全重放的请求进行有限重试；重试前使用指数退避，并避免把已显示的文本重复追加。

非流式成功、流式失败

先确认客户端、分组和渠道支持流式模式，再检查代理缓冲和解析器。排错时可以先把 stream 改回 false，确认基础请求仍然成功。