浏览器中使用 WebSocket
浏览器环境中 WebSocket 无法设置自定义请求头（包括 Authorization）。如需在前端使用，建议通过后端服务代理 WebSocket 连接，由后端在握手时注入鉴权头。
交互模式
Qwen-TTS-Realtime 提供两种交互模式，通过 session.update 事件的 session.mode 参数切换：
- server_commit 模式（推荐）：服务端智能处理文本分段和合成时机，适合大段文本的连续合成场景。客户端只需持续追加文本，无需关注切分。
- commit 模式：客户端主动提交文本缓冲区以触发合成，适合需要精确控制合成时机的场景（如对话式 AI 逐轮合成）。
交互流程
- Server commit 模式
- Commit 模式
将
session.update 事件的 session.mode 属性设置为 "server_commit" 以启用此模式。服务端会智能处理文本分割和合成时机。流程：- 客户端发送
session.update事件。服务端返回session.created和session.updated事件。 - 客户端发送
input_text_buffer.append事件，将文本追加到服务端缓冲区。 - 服务端智能处理文本分割和合成时机，返回
response.created、response.output_item.added、response.content_part.added和response.audio.delta事件。 - 完成响应后，服务端返回
response.audio.done、response.content_part.done、response.output_item.done和response.done。 - 客户端发送
session.finish，服务端返回session.finished结束会话。
| 生命周期 | 客户端事件 | 服务端事件 |
|---|---|---|
| 会话初始化 | session.update 会话配置 | session.created 会话已创建 |
session.updated 会话配置已更新 | ||
| 用户文本输入 | input_text_buffer.append 向服务端追加文本 | |
input_text_buffer.commit 立即合成服务端缓存的文本 | ||
session.finish 通知服务端不再有文本输入 | input_text_buffer.committed 服务端已接收提交的文本 | |
| 服务端音频输出 | 无 | response.created 服务端开始生成响应 |
response.output_item.added 响应中有新的输出内容 | ||
response.content_part.added 助手消息中添加了新的输出内容 | ||
response.audio.delta 模型生成的增量音频 | ||
response.content_part.done 内容流已完成 | ||
response.output_item.done 输出项流已完成 | ||
response.audio.done 音频生成完成 | ||
response.done 响应完成 |
连接生命周期
每次 WebSocket 连接对应一个独立会话。会话结束后连接关闭，无法复用。如需新一轮合成，请重新建立连接。
典型生命周期：
- 建立连接：客户端发起 WebSocket 握手，服务端验证 Authorization。
- 会话初始化：服务端发送
session.created，客户端可发送session.update配置参数。 - 文本输入与合成：客户端持续追加文本，服务端流式返回音频。
- 结束会话：客户端发送
session.finish，服务端刷新剩余音频并返回session.finished。 - 关闭连接：客户端收到
session.finished后主动关闭 WebSocket。
常见错误
| 错误 | 原因 | 解决方法 |
|---|---|---|
| HTTP 401/403 握手失败 | API Key 无效或缺失 | 确认 Authorization 头格式为 Bearer $DASHSCOPE_API_KEY |
| 连接立即断开 | URL 缺少 model 参数 | 确认 URL 包含 ?model=<model_id> |
error 事件 | 参数错误或模型不支持 | 检查 session.update 中的参数是否与所选模型兼容 |
only client commit mode supports clear operation | 在 server_commit 模式下发送了 input_text_buffer.clear | 仅在 commit 模式下使用 clear 操作 |
