开发指南
流式 API 使用指南:SSE、usage 与连接中断处理
配置 stream=true 和无缓冲读取,说明 SSE 用量、流式费用核对、超时与中断后避免重复提交的方法。
什么是流式响应#
流式请求允许结果分段返回。它能缩短看到首段文字的等待,但不会减少模型实际生成的 Token,也不代表整个任务已经成功结束。
本站支持常见 SSE 和 NDJSON 响应的用量捕获。实际响应格式取决于模型与协议,不同协议的结束事件和用量字段可能不同。
curl 流式示例#
先按第一条 API 请求设置环境变量并复制真实模型 ID。下面用 -N 关闭 curl 输出缓冲。
bash
curl --silent --show-error -N \
"$AI_ROUTER_API_BASE/chat/completions" \
-H "Authorization: Bearer $AI_ROUTER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "YOUR_MODEL_ID",
"messages": [{"role":"user","content":"给我一个三步写周报的方法。"}],
"max_tokens": 256,
"stream": true
}'生成请求会产生费用。OpenAI 兼容 SSE 通常使用 data: 行,应按事件边界解析;不要假设每次 TCP 读取就是一个完整 JSON。
在程序中处理事件#
维护读取缓冲区,按协议分割完整事件。解析正文增量与用量事件,收到结束信号后再标记完成;同时处理错误事件、连接中断和超时。
浏览器应用应通过自己的后端保管 API Key,避免把服务密钥嵌入公开前端代码。程序超时设置要区分首响应等待和整个输出过程。
如何核对流式费用#
平台会尝试获取上游 usage。不同协议可能把最终用量放在结束事件、单独事件或累计字段中。看到部分文字不说明最后用量已经收到。
若上游不返回可解析用量或连接提前中断,当前计费可能回退至预估值。需要核对时保存请求 ID 并查看平台账单,不要只用前端显示字数估算 Token。
连接中断后不要盲目重试#
中断只说明本地没有收到完整结果,上游可能仍已执行。自动重放同一付费 POST 可能生成第二笔调用。先查看用量状态、是否有异步任务 ID及已有结果,再决定下一步。
持续只有整段输出时,检查客户端、代理层和网关是否缓冲;如果非流式正常而流式不正常,先用这个最小示例区分网络与客户端问题。
准备好开始了吗?
在控制台选择账户可用模型,先用一条简单请求验证配置。