前提條件
DashScope Python SDK 版本需要不低於2.0.1。
快速開始
請求參數
下述請求參數可以通過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()方法手動建立)。
| 方法簽名 | 服務端響應事件(通過events()迭代下發) | 說明 |
|---|---|---|
session.created會話已建立session.updated 會話配置已更新 | 和服務端建立串連。進入with上下文時自動調用。 | |
session.updated會話配置已更新 | 更新本次會話互動的預設配置。參數配置請參考《請求參數》章節。在您建立連結,服務端會及時返回用於此會話的預設輸出輸入配置。如果您需要更新預設會話配置,我們也推薦您總是在建立連結後即刻調用此介面。服務端在收到session.update事件後,會進行參數校正,如果參數不合法則返回錯誤,否則更新服務端側的會話配置。 | |
| 無 | 發送原始事件。文本輸入通過input_text_buffer系列事件完成:將文本片段追加到雲端輸入文本緩衝區({"type": "input_text_buffer.append", "text": ...})。緩衝區是你可以寫入並稍後提交的臨時儲存。
| |
input_text_buffer.cleared清空服務端收到的文本 | 發送{"type": "input_text_buffer.clear"}事件,刪除當前雲端緩衝區的文本。 | |
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添加到雲端緩衝區的文本,並立刻合成所有文本。如果輸入的文本緩衝區為空白將產生錯誤。
| |
session.finished響應完成 | 發送session.finish事件,終止任務。之後繼續消費events()直到session.finished事件。 | |
| 無 | 關閉串連。退出with上下文時自動調用。 | |
| 無 | 擷取當前任務的session_id。 | |
| 無 | 擷取最近一次response的response_id。 | |
| 無 | 擷取首包音頻延遲。 |
事件迭代(events())
服務端會通過事件的方式,將服務端響應事件和資料返回給用戶端。在接收線程中迭代會話的events()處理服務端事件,session.finished事件後迭代結束;error事件會以DashScopeError異常拋出,可使用try/except捕獲。
| 方法 | 參數 | 傳回值 | 描述 |
|---|---|---|---|
event:服務端響應事件(dict)。 | 迭代器 | 包括對介面調用的回複響應和模型產生的文本和音頻,session.finished事件後迭代結束。具體可以參考:服務端事件 | |
event:服務端響應事件(dict)。 | 事件或None | 讀取一條服務端事件,正常關閉後返回None。 |