本文介绍通过 DashScope Python SDK 进行实时语音合成的关键接口、请求参数和示例代码。
本文介绍 DashScope Python SDK 调用实时语音合成时的关键接口与请求参数。
用户指南:关于模型介绍和选型建议请参见实时语音合成或非实时语音合成。
DashScope Python SDK 版本需要不低于1.25.11。
访问github下载更多示例代码。
下述请求参数可以通过QwenTtsRealtime的构造方法进行设置。
下述请求参数可以通过update_session接口配置。
QwenTtsRealtime通过
示例 1(方法签名):
示例 2(方法签名):
示例 3(方法签名):
示例 4(方法签名):
示例 5(方法签名):
示例 6(方法签名):
示例 7(方法签名):
示例 8(方法签名):
示例 9(方法签名):
示例 10(方法签名):
服务端会通过回调的方式,将服务端响应事件和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。
通过
示例 1(方法):
示例 2(方法):
示例 3(方法):
前期准备
DashScope Python SDK 版本需要不低于1.25.11。
快速开始
请求参数
下述请求参数可以通过QwenTtsRealtime的构造方法进行设置。
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| model | str | 是 | 模型名称。参见支持的模型。 |
| url | str | 是 | wss://maas.qianwenaiapi.com/api-ws/v1/realtime |
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| voice | str | 是 | 语音合成所使用的音色。参见支持的音色。 支持系统音色:
|
| language_type | str | 否 | 指定合成音频的语种,默认为 Auto。
|
| mode | str | 否 | 交互模式,可选值:
|
| format | str | 否 | 模型输出音频的格式。 支持的格式:
pcm。 |
| sample_rate | int | 否 | 模型输出音频的采样率(Hz)。 支持的采样率:
|
| speech_rate | float | 否 | 音频的语速。1.0为正常语速,小于1.0为慢速,大于1.0为快速。 默认值:1.0。 取值范围:[0.5, 2.0]。 千问-TTS-Realtime(参见支持的模型)不支持该参数。 |
| volume | int | 否 | 音频的音量。 默认值:50。 取值范围:[0, 100]。 千问-TTS-Realtime(参见支持的模型)不支持该参数。 |
| pitch_rate | float | 否 | 合成音频的语调。 默认值:1.0。 取值范围:[0.5, 2.0]。 千问-TTS-Realtime(参见支持的模型)不支持该参数。 |
| bit_rate | int | 否 | 指定音频的码率(kbps)。码率越大,音质越好,音频文件体积越大。仅在音频格式(response_format)为opus时可用。默认值:128。 取值范围:[6, 510]。 千问-TTS-Realtime(参见支持的模型)不支持该参数。 |
| instructions | str | 否 | 设置指令,参见指令控制。 默认值:无默认值,不设置不生效。 长度限制:长度不得超过 1600 Token。 支持语言:仅支持中文和英文。 指令控制功能已迁移至CosyVoice系列模型,详见指令控制。 |
| optimize_instructions | bool | 否 | 是否对 instructions 进行优化,以提升语音合成的自然度和表现力。默认值:False 行为说明:当设置为 True 时,系统将对 instructions 的内容进行语义增强与重写,生成更适合语音合成的内部指令。适用场景:推荐在追求高品质、精细化语音表达的场景下开启。 依赖关系:此参数依赖于 instructions 参数被设置。如果 instructions 为空,此参数不生效。指令控制功能已迁移至CosyVoice系列模型,详见指令控制。 |
关键接口
QwenTtsRealtime类
QwenTtsRealtime通过from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime方法引入。
| 方法签名 | 服务端响应事件(通过回调下发) | 说明 |
|---|---|---|
| 示例 1 请参见表格下方 | session.created > 会话已创建 session.updated > 会话配置已更新 | 和服务端创建连接。 |
| 示例 2 请参见表格下方 | session.updated > 会话配置已更新 | 更新本次会话交互的默认配置。参数配置请参考《请求参数》章节。 在您建立链接,服务端会及时返回用于此会话的默认输出输入配置。如果您需要更新默认会话配置,我们也推荐您总是在建立链接后即刻调用此接口。 服务端在收到session.update事件后,会进行参数校验,如果参数不合法则返回错误,否则更新服务端侧的会话配置。 |
| 示例 3 请参见表格下方 | 无 | 将文本片段追加到云端输入文本缓冲区。 缓冲区是你可以写入并稍后提交的临时存储。
|
| 示例 4 请参见表格下方 | input_text_buffer.cleared > 清空服务端收到的文本 | 删除当前云端缓冲区的文本。 |
| 示例 5 请参见表格下方 | input_text_buffer.committed > 提交文本并触发语音合成 response.output_item.added > 响应时有新的输出内容 response.content_part.added > 新的输出内容添加到assistant message 项 response.audio.delta > 模型增量生成的音频 response.audio.done > 完成音频生成 response.content_part.done > Assistant message 的音频内容流式输出完成 response.output_item.done > Assistant message 的整个输出项流式传输完成 response.done > 响应完成 | 提交之前通过append添加到云端缓冲区的文本,并立刻合成所有文本。如果输入的文本缓冲区为空将产生错误。
|
| 示例 6 请参见表格下方 | session.finished > 响应完成 | 终止任务。 |
| 示例 7 请参见表格下方 | 无 | 关闭连接。 |
| 示例 8 请参见表格下方 | 无 | 获取当前任务的session_id。 |
| 示例 9 请参见表格下方 | 无 | 获取最近一次response的response_id。 |
| 示例 10 请参见表格下方 | 无 | 获取首包音频延迟。 |
回调接口(QwenTtsRealtimeCallback)
服务端会通过回调的方式,将服务端响应事件和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。
通过from dashscope.audio.qwen_tts_realtime import QwenTtsRealtimeCallback引入。
| 方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| 示例 1 请参见表格下方 | 无 | 无 | 当和服务端建立连接完成后,该方法立刻被回调。 |
| 示例 2 请参见表格下方 | message:服务端响应事件。 | 无 | 包括对接口调用的回复响应和模型生成的文本和音频。具体可以参考:服务端事件 |
| 示例 3 请参见表格下方 | close_status_code:关闭WebSocket的状态码。 close_msg:关闭WebSocket的关闭信息。 | 无 | 当服务已经关闭连接后进行回调。 |