跳转到主要内容
千问云 home page
开放平台文档
实时

Qwen-TTS client events

WebSocket 客户端事件参考

客户端事件是通过 WebSocket 发送的 JSON 消息，用于配置语音参数、流式传输文本以及标记输入完成。
完整 API 概述请参阅实时流式语音合成。

端点

连接 WebSocket 端点： 
wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model={model}
将 {model} 替换为模型 ID，例如 qwen3-tts-instruct-flash-realtime。
URL 必须使用 wss:// 协议。Authorization 在请求头中设置（参见下方请求头），模型通过 URL 查询参数 model 指定。

请求头

请求头中需添加如下信息：
参数类型是否必选说明
Authorizationstring是鉴权令牌，格式为 Bearer <your_api_key>，将 <your_api_key> 替换为实际的 API Key。
user-agentstring否客户端标识，便于服务端追踪来源。
X-DashScope-WorkSpacestring否千问云业务空间 ID。
Authorization 鉴权在 WebSocket 握手阶段验证。如果 API Key 无效或缺失，握手将失败并返回 HTTP 401/403 错误。

事件概览

客户端事件服务端响应说明
（连接建立时，服务端主动发送）session.created服务端推送默认会话配置，客户端可据此决定是否发送 session.update
session.updatesession.updated设置语音、音频格式、模式等会话参数
input_text_buffer.appendresponse.created向合成缓冲区追加文本
input_text_buffer.commitinput_text_buffer.committed提交缓冲文本，开始合成
input_text_buffer.clearinput_text_buffer.cleared清空缓冲区中的所有文本
session.finishsession.finished结束会话；服务端刷新剩余音频，客户端收到后应主动关闭连接

session.update

WebSocket 连接建立后，服务端会主动发送 session.created 事件，包含默认会话配置。客户端可在收到后发送 session.update 覆盖默认配置；省略则保持默认值。服务端返回 session.updated 确认。
Example
{
  "event_id": "event_123",
  "type": "session.update",
  "session": {
    "voice": "Cherry",
    "mode": "server_commit",
    "language_type": "Chinese",
    "response_format": "pcm",
    "sample_rate": 24000,
    "instructions": "",
    "optimize_instructions": false
  }
}
​
string
body
必填
事件唯一标识符，在会话中必须唯一。
​
string
body
必填
设置为 session.update。
​
object
body
会话配置。

input_text_buffer.append

向合成缓冲区追加文本。server_commit 模式下缓冲区在服务端，commit 模式下在客户端。 新的响应开始时，服务端返回 response.created。
Example
{
  "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
  "type": "input_text_buffer.append",
  "text": "Hello, I am Qwen."
}
​
string
body
必填
事件唯一标识符，在会话中必须唯一。
​
string
body
必填
设置为 input_text_buffer.append。
​
string
body
必填
待合成的文本。

input_text_buffer.commit

提交缓冲文本并创建用户消息项。服务端返回 input_text_buffer.committed。对空缓冲区执行此操作会返回错误。 不同模式下的行为：
  • server_commit：立即合成所有缓冲文本。服务端停止缓存并处理全部内容。
  • commit：将缓冲文本创建为用户消息项。
提交仅触发语音合成，不会触发模型响应生成。
Example
{
  "event_id": "event_C7p2MKVFXqrA3TBzNJUse",
  "type": "input_text_buffer.commit"
}
​
string
body
必填
事件唯一标识符，在会话中必须唯一。
​
string
body
必填
设置为 input_text_buffer.commit。

input_text_buffer.clear

清空缓冲区中的所有文本。服务端返回 input_text_buffer.cleared。
仅在 mode: "commit" 时可用。server_commit 模式下发送此事件，服务端会返回错误：only client commit mode supports clear operation。
Example
{
  "event_id": "event_2728",
  "type": "input_text_buffer.clear"
}
​
string
body
必填
事件唯一标识符，在会话中必须唯一。
​
string
body
必填
设置为 input_text_buffer.clear。

session.finish

通知服务端没有更多文本需要发送。服务端刷新剩余音频，返回 session.finished；客户端应在收到此事件后主动关闭连接。
Example
{
  "event_id": "event_2239",
  "type": "session.finish"
}
​
string
body
必填
事件唯一标识符，在会话中必须唯一。
​
string
body
必填
设置为 session.finish。