本文介绍 DashScope Python SDK 调用 Qwen-TTS-Realtime 系列模型时的关键接口与请求参数。
前期准备
DashScope Python SDK 版本需要不低于2.0.1。
快速开始
import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor
import dashscope
text_to_synthesize = [
'对吧~我就特别喜欢这种超市,',
'尤其是过年的时候',
'去逛超市',
'就会觉得',
'超级超级开心!',
'想买好多好多的东西呢!'
]
# The API Key differs between the Singapore and Beijing regions. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# Receiving thread: iterate over the server events and write the audio to the file incrementally
def receive_events(session):
with open('result_24k.pcm', 'wb') as f:
for event in session.events():
event_type = event.get('type')
if event_type == 'session.created':
print('start session: {}'.format(event['session']['id']))
elif event_type == 'response.audio.delta':
f.write(base64.b64decode(event['delta']))
elif event_type == 'response.done':
print(f'response {session.last_response_id} done')
elif event_type == 'session.finished':
print('session finished')
if __name__ == '__main__':
print('Initializing ...')
# Create a real-time speech synthesis session: entering the with context automatically establishes the connection
with client.audio.realtime.connect(
model='qwen3-tts-flash-realtime',
) as session:
session.update_session(
output_modalities=['audio'],
voice='Cherry',
response_format='pcm',
sample_rate=24000,
mode='server_commit'
)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, session)
for text_chunk in text_to_synthesize:
print(f'send text: {text_chunk}')
session.send_event({'type': 'input_text_buffer.append', 'text': text_chunk})
time.sleep(0.1)
# Notify the server that the input is complete (in server_commit mode the server decides when to synthesize)
session.end_session()
receiver.result()
print('[Metric] session: {}, first audio delay: {}'.format(
session.session_id,
session.last_first_audio_delay,
))
import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor
import dashscope
text_to_synthesize = [
'这是第一句话。',
'这是第二句话。',
'这是第三句话。',
]
# The API Key differs between the Singapore and Beijing regions. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# Receiving thread: iterate over the server events and write the audio to the file incrementally
def receive_events(session):
with open('result_24k.pcm', 'wb') as f:
for event in session.events():
event_type = event.get('type')
if event_type == 'session.created':
print('start session: {}'.format(event['session']['id']))
elif event_type == 'response.audio.delta':
f.write(base64.b64decode(event['delta']))
elif event_type == 'response.done':
print(f'response {session.last_response_id} done')
elif event_type == 'session.finished':
print('session finished')
if __name__ == '__main__':
print('Initializing ...')
# Create a real-time speech synthesis session: entering the with context automatically establishes the connection
with client.audio.realtime.connect(
model='qwen3-tts-flash-realtime',
) as session:
session.update_session(
output_modalities=['audio'],
voice='Cherry',
response_format='pcm',
sample_rate=24000,
mode='commit'
)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, session)
for text in text_to_synthesize:
print(f'send text: {text}')
session.send_event({'type': 'input_text_buffer.append', 'text': text})
# In commit mode the client triggers the synthesis
session.send_event({'type': 'input_text_buffer.commit'})
time.sleep(0.1)
session.end_session()
receiver.result()
print('[Metric] session: {}, first audio delay: {}'.format(
session.session_id,
session.last_first_audio_delay,
))
访问github下载更多示例代码。
请求参数
下述请求参数可以通过client.audio.realtime的connect方法设置。
参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | str | 是 | 模型名称。参见支持的模型。 |
ws_url | str | 否 | 会话端点。缺省时由Client构造参数 |
下述请求参数可以通过会话的update_session方法配置(具名参数直接传入,其余参数透传至session.update事件的session对象)。
参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
voice | str | 是 | 语音合成所使用的音色。参见Qwen-TTS音色列表。 |
language_type | str | 否 | 指定合成音频的语种,默认为
|
mode | str | 否 | 交互模式,可选值:
|
response_format | str | 否 | 模型输出音频的格式。 支持的格式:
|
sample_rate | int | 否 | 模型输出音频的采样率(Hz)。 支持的采样率:
|
speech_rate | float | 否 | 音频的语速。1.0为正常语速,小于1.0为慢速,大于1.0为快速。 默认值:1.0。 取值范围:[0.5, 2.0]。 |
volume | int | 否 | 音频的音量。 取值范围:[0, 100]。 |
pitch_rate | float | 否 | 合成音频的语调。 默认值:1.0。 取值范围:[0.5, 2.0]。 |
bit_rate | int | 否 |
关键接口
会话(RealtimeSession)
实时语音合成会话通过client.audio.realtime.connect(model=...)创建,进入with上下文时自动建立连接(也可调用会话的connect()方法手动建立)。
方法签名 | 服务端响应事件(通过 | 说明 |
|---|---|---|
|
| 和服务端创建连接。进入 |
|
| 更新本次会话交互的默认配置。参数配置请参考《请求参数》章节。 在您建立链接,服务端会及时返回用于此会话的默认输出输入配置。如果您需要更新默认会话配置,我们也推荐您总是在建立链接后即刻调用此接口。 服务端在收到session.update事件后,会进行参数校验,如果参数不合法则返回错误,否则更新服务端侧的会话配置。 |
| 无 | 发送原始事件。文本输入通过
|
|
| 发送 |
|
| 发送
|
|
| 发送session.finish事件,终止任务。之后继续消费 |
| 无 | 关闭连接。退出 |
| 无 | 获取当前任务的session_id。 |
| 无 | 获取最近一次response的response_id。 |
| 无 | 获取首包音频延迟。 |
事件迭代(events())
服务端会通过事件的方式,将服务端响应事件和数据返回给客户端。在接收线程中迭代会话的events()处理服务端事件,session.finished事件后迭代结束;error事件会以DashScopeError异常抛出,可使用try/except捕获。
方法 | 参数 | 返回值 | 描述 |
|---|---|---|---|
| event:服务端响应事件( | 迭代器 | 包括对接口调用的回复响应和模型生成的文本和音频, |
| event:服务端响应事件( | 事件或 | 读取一条服务端事件,正常关闭后返回 |