即時語音合成API用戶端事件參考-大模型服務平台百鍊-阿里雲

本文介紹 Qwen-TTS Realtime API 的用戶端事件。

相關文檔：即時語音合成-千問。

session.update

用於更新會話配置。在WebSocket串連建立成功後，可立即發送此事件作為互動的第一步。如果未發送，系統將使用預設配置。服務端成功處理此事件後，會返回session.updated事件作為確認。

event_id string （必選）

用戶端產生的唯一事件ID。在單次WebSocket串連會話中必須保持唯一。強烈建議使用 UUID（通用唯一識別碼）。

{
    "event_id": "event_123",
    "type": "session.update",
    "session": {
        "voice": "Cherry",
        "mode": "server_commit",
        "language_type": "Chinese",
        "response_format": "pcm",
        "sample_rate": 24000,
        "instructions": "",
        "optimize_instructions": false
    }
}

type string （必選）

事件類型，固定為session.update。

session object （可選）

會話配置。

屬性

voice string （必選）

語音合成所使用的音色。參見支援的音色。

支援系統音色和專屬音色：

系統音色：僅限千問3-TTS-Instruct-Flash-Realtime、千問3-TTS-Flash-Realtime和千問-TTS-Realtime系列模型。音色效果請參見：支援的音色。
專屬音色
- 聲音複刻（Qwen）功能定製的音色：僅限千問3-TTS-VC-Realtime系列模型
- 聲音設計（Qwen）功能定製的音色：僅限千問3-TTS-VD-Realtime系列模型

mode string （可選）

互動模式，可選值：

server_commit（預設）：服務端自動判斷合成時機，平衡延遲與品質，推薦大多數情境使用
commit：用戶端手動觸發合成，延遲最低，但需自行管理句子完整性

language_type string （可選）

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

Auto：適用無法確定文本的語種或文本包含多種語言的情境，模型會自動為文本中的不同語言片段匹配各自的發音，但無法保證發音完全精準。
指定語種：適用於文本為單一語種的情境，此時指定為具體語種，能顯著提升合成品質，效果通常優於 Auto。可選值包括：
- Chinese
- English
- German
- Italian
- Portuguese
- Spanish
- Japanese
- Korean
- French
- Russian

response_format string （可選）

模型輸出音訊格式。

支援的格式：

pcm（預設）
wav
mp3
opus

千問-TTS-Realtime（參見支援的模型）僅支援pcm。

sample_rate integer （可選）

模型輸出音訊採樣率（Hz）。

支援的採樣率：

8000
16000
24000（預設）
48000

千問-TTS-Realtime（參見支援的模型）僅支援24000。

speech_rate float （可選）

音訊語速。1.0為正常語速，小於1.0為慢速，大於1.0為快速。

預設值：1.0。

取值範圍：[0.5, 2.0]。

千問-TTS-Realtime（參見支援的模型）不支援該參數。

volume integer （可選）

音訊音量。

預設值：50。

取值範圍：[0, 100]。

千問-TTS-Realtime（參見支援的模型）不支援該參數。

pitch_rate float （可選）

合成音訊語調。

預設值：1.0。

取值範圍：[0.5, 2.0]。

千問-TTS-Realtime（參見支援的模型）不支援該參數。

bit_rate integer （可選）

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

預設值：128。

取值範圍：[6, 510]。

千問-TTS-Realtime（參見支援的模型）不支援該參數。

instructions string （可選）

設定指令，參見即時語音合成-千問。

預設值：無預設值，不設定不生效。

長度限制：長度不得超過 1600 Token。

支援語言：僅支援中文和英文。

適用範圍：該功能僅適用於千問3-TTS-Instruct-Flash-Realtime系列模型。

optimize_instructions boolean （可選）

是否對 instructions 進行最佳化，以提升語音合成的自然度和表現力。

預設值：false。

行為說明：當設定為 true 時，系統將對 instructions 的內容進行語義增強與重寫，產生更適合語音合成的內部指令。

適用情境：推薦在追求高品質、精細化語音表達的情境下開啟。

依賴關係：此參數依賴於 instructions 參數被設定。如果 instructions 為空白，此參數不生效。

適用範圍：該功能僅適用於千問3-TTS-Instruct-Flash-Realtime系列模型。

input_text_buffer.append

用於將待合成文本追加到文本緩衝區。在server_commit模式中，文本將追加到服務端的文本緩衝區；在commit模式中，文本將追加到用戶端的文本緩衝區。

event_id string （必選）

用戶端產生的唯一事件ID。在單次WebSocket串連會話中必須保持唯一。強烈建議使用 UUID（通用唯一識別碼）。

{
  "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
  "type": "input_text_buffer.append",
  "text": "您好，我是千問。"
}

type string （必選）

事件類型，固定為input_text_buffer.append。

text string （必選）

待合成文本。

input_text_buffer.commit

用於提交使用者輸入文本緩衝區，從而在對話中建立新的使用者訊息項。如果輸入的文本緩衝區為空白，此事件將產生錯誤。處於“server_commit”模式時，使用者提交此事件，表示立即合成之前的所有文本，伺服器不再緩衝文本。處於“commit”模式時，用戶端必須提交文本緩衝區才能建立使用者訊息項。提交輸入文本緩衝區不會從模型建立響應，伺服器將返回 input_text_buffer.committed 事件進行響應。

event_id string （必選）

用戶端產生的唯一事件ID。在單次WebSocket串連會話中必須保持唯一。強烈建議使用 UUID（通用唯一識別碼）。

{
  "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
  "type": "input_text_buffer.commit"
}

type string （必選）

事件類型，固定為input_text_buffer.commit。

input_text_buffer.clear

用於清除緩衝區中的文本。服務端返回input_text_buffer.cleared 事件進行響應。

event_id string （必選）

用戶端產生的唯一事件ID。在單次WebSocket串連會話中必須保持唯一。強烈建議使用 UUID（通用唯一識別碼）。

{
  "event_id": "event_2728",
  "type": "input_text_buffer.clear"
}

type string （必選）

事件類型，固定為input_text_buffer.clear。

session.finish

用戶端發送 session.finish 事件通知服務端不再有文本輸入，服務端將剩餘音頻返回，隨後關閉串連。

event_id string （必選）

用戶端產生的唯一事件ID。在單次WebSocket串連會話中必須保持唯一。強烈建議使用 UUID（通用唯一識別碼）。

{
  "event_id": "event_2239",
  "type": "session.finish"
}

type string （必選）

事件類型，固定為session.finish。