本文介绍 Qwen-Audio-TTS 实时语音合成服务中客户端通过 WebSocket 发送给服务端的客户端事件,包括 run-task(启动任务)、continue-task(流式输入文本)、finish-task(结束任务)的字段与发送时机。
事件交互流程
- 发送 run-task 启动并配置任务,等待 task-started。
- 收到
task-started后,通过 continue-task 发送文本,同时接收 result-generated 和合成音频。 - 文本全部发送完毕后,发送 finish-task,继续接收剩余结果和音频,直到收到 task-finished;任务失败时返回 task-failed。
result-generated 返回句子元信息,音频数据通过独立通道传输:WebSocket 使用二进制帧,AOQ 使用 Audio Track。连接、鉴权和音频传输方式请参见 WebSocket API 或 AOQ 接入。
run-task
建立连接后,客户端立即发送 run-task 事件,启动语音合成任务并设置模型、音色、采样率等参数。
收到
task-started 后才能发送 continue-task。 run-task 只用于启动和配置任务,待合成文本通过 continue-task 发送。| 参数 | 类型 | 说明 |
|---|---|---|
| header | object | (必选) |
| header.action | string | (必选) 指令类型,固定为 run-task。 |
| header.task_id | string | (必选) 客户端生成的任务 ID(UUID 格式),用于关联后续事件。和后续 continue-task、finish-task 中的 task_id 保持一致。 |
| header.streaming | string | (必选) 固定为 duplex |
| payload | object | (必选) |
| payload.task_group | string | (必选) 任务组,固定为 audio。 |
| payload.task | string | (必选) 任务类型,固定为 tts。 |
| payload.function | string | (必选) 功能类型,固定为 SpeechSynthesizer。 |
| payload.model | string | (必选) 模型名称。 |
| payload.input | object | (必选) 输入数据:固定为空对象 {},待合成文本通过 continue-task 指令发送。 |
| payload.parameters | object | (必选) 语音合成参数。 |
| payload.parameters.text_type | string | (必选) 固定为 PlainText。 |
| payload.parameters.voice | string | (必选) 语音合成所使用的音色。
|
| payload.parameters.format | string | (可选) 音频编码格式。 取值范围:
|
| payload.parameters.sample_rate | integer | (可选) 音频采样率(Hz)。 取值范围:8000, 16000, 22050(默认), 24000, 44100, 48000。 |
| payload.parameters.volume | integer | (可选) 音量。 默认值:50。 取值范围:[0, 100]。 |
| payload.parameters.rate | float | (可选) 语速。 默认值:1.0。 取值范围:[0.5, 2.0]。 |
| payload.parameters.pitch | float | (可选) 音调。 默认值:1.0。 取值范围:[0.5, 2.0]。 |
| payload.parameters.bit_rate | integer | (可选) 音频码率(kbps)。音频格式为mp3或opus时,支持通过bit_rate参数调整码率。 默认值:32。 取值范围:[6, 510]。 |
| payload.parameters.enable_ssml | boolean | (可选) 是否开启 SSML 功能。 默认值:false。 设为 true 后,仅允许发送一次 continue-task 指令。 SSML 的使用限制(支持的模型、音色和接口),请参见使用限制。 |
| payload.parameters.word_timestamp_enabled | boolean | (可选) 是否开启字级别时间戳。 默认值:false。 仅在流式输出模式下可用。支持复刻音色;支持的系统音色请参见Qwen-Audio-TTS音色列表。 |
| payload.parameters.seed | integer | (可选) 生成时使用的随机数种子,使合成的效果产生变化。在模型版本、文本、音色及其他参数均相同的前提下,使用相同的seed可复现相同的合成结果。 默认值0。 取值范围:[0, 65535]。 |
| payload.parameters.language_hints | array[string] | (可选) 提示: 使用 qwen-audio-3.1-tts-flash 的多语种与方言音色时,可通过此参数指定语种或方言。具体用法请参见多语种与方言音色的设置方法。 - 此参数为数组,但当前版本仅处理第一个元素,因此建议只传入一个值。
|
| payload.parameters.instruction | string | (可选) 设置指令,用于控制方言、情感或角色等合成效果。具体使用说明请参见指令控制。 |
| payload.parameters.enable_aigc_tag | boolean | (可选) 是否在生成的音频中添加AIGC隐性标识。设置为true时,会将隐性标识嵌入到支持格式(wav/mp3/opus)的音频中。 默认值:false。 |
| payload.parameters.aigc_propagator | string | (可选) 设置AIGC隐性标识中的 ContentPropagator 字段,用于标识内容的传播者。仅在 enable_aigc_tag 为 true 时生效。 |
| payload.parameters.aigc_propagate_id | string | (可选) 设置AIGC隐性标识中的 PropagateID 字段,用于唯一标识一次具体的传播行为。仅在 enable_aigc_tag 为 true 时生效。 默认值:本次语音合成请求Request ID。 |
| payload.parameters.hot_fix | object | (可选) 文本热修复配置,用于自定义指定词语的发音或对待合成文本进行替换。 参数介绍:
|
| payload.parameters.enable_markdown_filter | boolean | (可选) 是否启用 Markdown 过滤。启用后,服务会在合成前将 Markdown 转换成适合朗读的文本。 默认值:false。设为 true 启用。 |
continue-task
收到 task-started 后,客户端发送 continue-task 事件提交待合成文本。文本可一次性发送,也可分段按顺序发送。
| 参数 | 类型 | 说明 |
|---|---|---|
| header | object | (必选) |
| header.action | string | (必选) 指令类型,固定为 continue-task。 |
| header.task_id | string | (必选) 任务 ID(UUID 格式),需要和 run-task 中的 task_id 保持一致。 |
| header.streaming | string | (必选) 固定为 duplex。 |
| payload | object | (必选) |
| payload.input | object | (必选) 包含待合成文本。 |
| payload.text | string | (必选) 待合成文本。单次最多 20000 字符,累计最多 200000 字符。 |
finish-task
所有文本发送完毕后,客户端立即发送 finish-task 事件,通知服务端文本发送完毕并请求结束任务。如需取消当前轮次的合成,可在 input 中将 directive 设为 cancel。
发送
finish-task 后,仍需接收剩余合成结果和音频,直到收到 task-finished。 取消任务时,服务端停止输出后续音频并返回 task-finished。| 参数 | 类型 | 说明 |
|---|---|---|
| header | object | (必选) |
| header.action | string | (必选) 指令类型,固定为 finish-task。 |
| header.task_id | string | (必选) 任务 ID(UUID 格式),需要和 run-task 中的 task_id 保持一致。 |
| header.streaming | string | (必选) 固定为 duplex |
| payload | object | (必选) |
| payload.input | object | (必选) 任务输入。为空对象 {} 时表示正常结束任务;包含 directive 时可用于取消当前轮次的语音合成任务。 |
| payload.directive | string | (可选) 控制任务结束行为。当前仅支持取值为 cancel,表示取消当前轮次的语音合成任务,服务端会立即返回 task-finished 事件,且不会输出后续音频。 取消后,可在当前 WebSocket 连接上重新发起语音合成任务(发送新的 run-task 事件),无需重新建立连接。 |