全部產品
Search
文件中心

Alibaba Cloud Model Studio:Python SDK

更新時間:Oct 29, 2026

本文介紹 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 = [
    '對吧~我就特別喜歡這種超市,',
    '尤其是過年的時候',
    '去逛超市',
    '就會覺得',
    '超級超級開心!',
    '想買好多好多的東西呢!'
]

# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請將下行替換為您的阿里雲百鍊API Key:api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡(ap-southeast-1)地區的配置。調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區配置不同。
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# 接收線程:迭代服務端事件,將音頻增量寫入檔案
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 ...')

    # 建立即時語音合成會話:進入with上下文時自動建立串連
    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)
            # 通知服務端輸入完成(server_commit模式下由服務端決定合成時機)
            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 = [
    '這是第一句話。',
    '這是第二句話。',
    '這是第三句話。',
]

# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請將下行替換為您的阿里雲百鍊API Key:api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡(ap-southeast-1)地區的配置。調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區配置不同。
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# 接收線程:迭代服務端事件,將音頻增量寫入檔案
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 ...')

    # 建立即時語音合成會話:進入with上下文時自動建立串連
    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})
                # commit模式下由用戶端觸發合成
                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構造參數workspace/region自動推導(華北2(北京)地區:wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime;新加坡地區:wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime)。

下述請求參數可以通過會話的update_session方法配置(具名參數直接傳入,其餘參數透傳至session.update事件的session對象)。

參數

類型

是否必須

說明

voice

str

是

語音合成所使用的音色。參見Qwen-TTS音色列表。

language_type

str

否

指定合成音訊語種,預設為 Auto。

  • Auto:適用無法確定文本的語種或文本包含多種語言的情境,模型會自動為文本中的不同語言片段匹配各自的發音,但無法保證發音完全精準。

  • 指定語種:適用於文本為單一語種的情境,此時指定為具體語種,能顯著提升合成品質,效果通常優於 Auto。可選值包括:

    • Chinese

    • English

    • German

    • Italian

    • Portuguese

    • Spanish

    • Japanese

    • Korean

    • French

    • Russian

mode

str

否

互動模式,可選值:

  • server_commit(預設):服務端自動判斷合成時機,平衡延遲與品質,推薦大多數情境使用

  • commit:用戶端手動觸發合成,延遲最低,但需自行管理句子完整性

response_format

str

否

模型輸出音訊格式。

支援的格式:

  • pcm(預設)

  • wav

  • mp3

  • opus

sample_rate

int

否

模型輸出音訊採樣率(Hz)。

支援的採樣率:

  • 8000

  • 16000

  • 24000(預設)

  • 48000

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

否

指定音訊碼率(kbps)。碼率越大,音質越好,音頻檔案體積越大。僅在音頻格式(response_format)為opus時可用。

預設值:128。

取值範圍:[6, 510]。

關鍵介面

會話(RealtimeSession)

即時語音合成會話通過client.audio.realtime.connect(model=...)建立,進入with上下文時自動建立串連(也可調用會話的connect()方法手動建立)。

方法簽名

服務端響應事件(通過events()迭代下發)

說明

def connect(self) -> "RealtimeSession"

session.created

會話已建立

session.updated

會話配置已更新

和服務端建立串連。進入with上下文時自動調用。

def update_session(self,
                   output_modalities: List[str],
                   *,
                   voice: str = None,
                   **kwargs) -> None

session.updated

會話配置已更新

更新本次會話互動的預設配置。參數配置請參考《請求參數》章節。

在您建立連結,服務端會及時返回用於此會話的預設輸出輸入配置。如果您需要更新預設會話配置,我們也推薦您總是在建立連結後即刻調用此介面。

服務端在收到session.update事件後,會進行參數校正,如果參數不合法則返回錯誤,否則更新服務端側的會話配置。

def send_event(self,
               event: Dict[str, Any]) -> None

無

發送原始事件。文本輸入通過input_text_buffer系列事件完成:將文本片段追加到雲端輸入文本緩衝區({"type": "input_text_buffer.append", "text": ...})。緩衝區是你可以寫入並稍後提交的臨時儲存。

  • "server_commit"模式下,伺服器決定何時提交併合成文本緩衝區中的文本。
  • "commit"模式下,用戶端需要主動發送input_text_buffer.commit事件觸發語音合成。
def send_event(self,
               event: Dict[str, Any]) -> None

input_text_buffer.cleared

清空服務端收到的文本

發送{"type": "input_text_buffer.clear"}事件,刪除當前雲端緩衝區的文本。

def send_event(self,
               event: Dict[str, Any]) -> None

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

響應完成

發送{"type": "input_text_buffer.commit"}事件,提交之前通過append添加到雲端緩衝區的文本,並立刻合成所有文本。如果輸入的文本緩衝區為空白將產生錯誤。

  • "server_commit"模式下,用戶端不需要發送此事件,伺服器會自動認可文本緩衝區。
  • "commit"模式下,用戶端必須通過commit觸發語音合成。
def end_session(self) -> None

session.finished

響應完成

發送session.finish事件,終止任務。之後繼續消費events()直到session.finished事件。

def close(self, ) -> None

無

關閉串連。退出with上下文時自動調用。

session.session_id

無

擷取當前任務的session_id。

session.last_response_id

無

擷取最近一次response的response_id。

session.last_first_audio_delay

無

擷取首包音頻延遲。

事件迭代(events())

服務端會通過事件的方式,將服務端響應事件和資料返回給用戶端。在接收線程中迭代會話的events()處理服務端事件,session.finished事件後迭代結束;error事件會以DashScopeError異常拋出,可使用try/except捕獲。

方法

參數

傳回值

描述

def events(self) -> Iterator[Dict]

event:服務端響應事件(dict)。

迭代器

包括對介面調用的回複響應和模型產生的文本和音頻,session.finished事件後迭代結束。具體可以參考:服務端事件

def recv_event(self) -> Optional[Dict]

event:服務端響應事件(dict)。

事件或None

讀取一條服務端事件,正常關閉後返回None。