实时语音合成 Java SDK
模型和音色选项请参见实时流式语音合成。
两种交互模式的使用流程相同：构建
构建
构建
快速开始
两种交互模式的使用流程相同：构建 QwenTtsRealtimeParam，创建带回调的 QwenTtsRealtime 实例，连接服务、配置会话、发送文本并关闭连接。完整示例和教程请参见实时语音合成。
- 服务端提交模式（
server_commit）：由服务端决定何时合成缓冲区中的文本，适用于大多数场景。 - 客户端提交模式（
commit）：由客户端调用commit()触发合成，延迟最低，但需要自行管理句子边界。
请求参数
QwenTtsRealtimeParam
构建 QwenTtsRealtimeParam 对象，传入 QwenTtsRealtime 构造函数。
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
| model | String | 是 | 模型名称。参见支持的模型。 |
| url | String | 否 | WebSocket 端点。默认值：wss://dashscope.aliyuncs.com/api-ws/v1/realtime，无需显式设置；仅连接自定义端点时才需指定。 |
QwenTtsRealtimeConfig
构建 QwenTtsRealtimeConfig 对象，传入 updateSession() 方法。
| 参数 | 类型 | 必选 | 说明 |
|---|---|---|---|
| voice | String | 是 | 合成音色。系统音色：适用于 Qwen3-TTS-Instruct-Flash-Realtime、Qwen3-TTS-Flash-Realtime 和 Qwen-TTS-Realtime。试听请参见支持的音色。自定义音色：通过声音复刻（Qwen）创建（仅限 Qwen3-TTS-VC-Realtime）或通过声音设计（Qwen）创建（仅限 Qwen3-TTS-VD-Realtime）。 |
| languageType | String | 否 | 输出音频的语言。默认值：Auto（模型按片段自动检测语言，准确性无法保证）。指定语言可提升单语言文本的合成质量。可选值：Chinese、English、German、Italian、Portuguese、Spanish、Japanese、Korean、French、Russian。 |
| mode | String | 否 | 交互模式。server_commit（默认）：服务端自动决定合成时机，兼顾延迟和质量。commit：客户端触发合成，延迟最低，需自行管理句子边界。 |
| format | String | 否 | 音频输出格式。可选值：pcm（默认）、wav、mp3、opus。Qwen-TTS-Realtime 仅支持 pcm。参见支持的模型。 |
| sampleRate | int | 否 | 采样率，单位 Hz。可选值：8000、16000、24000（默认）、48000。Qwen-TTS-Realtime 仅支持 24000。参见支持的模型。 |
| speechRate | float | 否 | 语速倍率。范围：[0.5, 2.0]，默认值：1.0。Qwen-TTS-Realtime 不支持此参数。 |
| volume | int | 否 | 音量。范围：[0, 100]，默认值：50。Qwen-TTS-Realtime 不支持此参数。 |
| pitchRate | float | 否 | 音调倍率。范围：[0.5, 2.0]，默认值：1.0。Qwen-TTS-Realtime 不支持此参数。 |
| bitRate | int | 否 | 音频比特率，单位 kbps。范围：[6, 510]，默认值：128。仅适用于 opus 格式，值越高音质越好但文件越大。Qwen-TTS-Realtime 不支持此参数。 |
| instructions | String | 否 | 用于控制语音风格的指令文本，最长 1,600 tokens，仅支持中文和英文。仅适用于 Qwen3-TTS-Instruct-Flash-Realtime。参见指令控制。 |
| optimizeInstructions | boolean | 否 | 优化 instructions 以获得更自然的合成效果。默认值：false。未设置 instructions 时无效。仅适用于 Qwen3-TTS-Instruct-Flash-Realtime。 |
| enableTn | boolean | 否 | 是否启用文本归一化（Text Normalization）。默认值：true。 |
API 参考
QwenTtsRealtime 类
| 方法 | 签名 | 服务端事件 | 说明 |
|---|---|---|---|
| connect | public void connect() throws NoApiKeyException, InterruptedException | session.created、session.updated | 建立 WebSocket 连接。 |
| updateSession | public void updateSession(QwenTtsRealtimeConfig config) | session.updated | 更新会话配置。在 connect() 之后立即调用以覆盖默认设置。服务端会校验参数，无效时返回错误。 |
| appendText | public void appendText(String text) | 无 | 向服务端输入缓冲区追加文本。server_commit 模式下由服务端决定合成时机；commit 模式下需调用 commit() 触发合成。 |
| clearAppendedText | public void clearAppendedText() | input_text_buffer.cleared | 清空服务端输入缓冲区中的所有文本。 |
| commit | public void commit() | input_text_buffer.committed、response.output_item.added、response.content_part.added、response.audio.delta、response.audio.done、response.content_part.done、response.output_item.done、response.done | 提交缓冲区文本并开始合成。缓冲区为空时返回错误。server_commit 模式下服务端自动提交；commit 模式下需调用此方法触发合成。 |
| finish | public void finish() | session.finished | 停止当前任务。 |
| close | public void close() | 无 | 关闭 WebSocket 连接。 |
| getSessionId | public String getSessionId() | 无 | 返回当前会话 ID。 |
| getResponseId | public String getResponseId() | 无 | 返回最近一次响应 ID。 |
| getFirstAudioDelay | public long getFirstAudioDelay() | 无 | 返回首个音频包的延迟时间，单位毫秒。 |
| cancelResponse | public void cancelResponse() | 无 | 取消当前合成响应。 |
QwenTtsRealtimeCallback 接口
| 方法 | 参数 | 说明 |
|---|---|---|
onOpen() | 无 | WebSocket 连接建立时调用。 |
onEvent(JsonObject message) | message：服务端事件数据。 | 收到服务端事件时调用。事件类型参见服务端事件。 |
onClose(int code, String reason) | code：WebSocket 关闭状态码。reason：关闭原因。 | 服务端关闭连接时调用。 |
后续步骤
- 实时流式语音合成：模型、支持的音色和指令控制。
- 服务端事件：WebSocket 事件类型参考。
- 声音复刻（Qwen）：使用 Qwen3-TTS-VC-Realtime 创建自定义音色。
- 声音设计（Qwen）：使用 Qwen3-TTS-VD-Realtime 设计自定义音色。
- GitHub 示例：更多代码示例。
