即時語音合成（Qwen-TTS-Realtime）
本文介紹 Qwen-TTS Realtime API 的用戶端事件。
相關文檔：即時語音合成-千問。
session.update
用於更新會話配置。在WebSocket串連建立成功後，可立即發送此事件作為互動的第一步。如果未發送，系統將使用預設配置。服務端成功處理此事件後，會返回session.updated事件作為確認。
event_idstring（必選）用戶端產生的唯一事件ID。在單次WebSocket串連會話中必須保持唯一。強烈建議使用 UUID（通用唯一識別碼）。typestring（必選）事件類型，固定為session.update。sessionobject（可選）會話配置。
voicestring（必選）語音合成所使用的音色。參見支援的音色。支援系統音色和專屬音色：
-
系統音色：僅限千問3-TTS-Instruct-Flash-Realtime、千問3-TTS-Flash-Realtime和千問-TTS-Realtime系列模型。音色效果請參見：支援的音色。
-
專屬音色
modestring（可選）互動模式，可選值：
server_commit（預設）：服務端自動判斷合成時機，平衡延遲與品質，推薦大多數情境使用commit：用戶端手動觸發合成，延遲最低，但需自行管理句子完整性 language_typestring（可選）指定合成音訊語種，預設為 Auto。
-
Auto：適用無法確定文本的語種或文本包含多種語言的情境，模型會自動為文本中的不同語言片段匹配各自的發音，但無法保證發音完全精準。
-
指定語種：適用於文本為單一語種的情境，此時指定為具體語種，能顯著提升合成品質，效果通常優於
Auto。可選值包括：
ChineseEnglishGermanItalianPortugueseSpanishJapaneseKoreanFrenchRussian
response_formatstring（可選）模型輸出音訊格式。支援的格式：千問-TTS-Realtime（參見支援的模型）僅支援pcm。sample_rateinteger（可選）模型輸出音訊採樣率（Hz）。支援的採樣率：
- 8000
- 16000
- 24000（預設）
- 48000
千問-TTS-Realtime（參見支援的模型）僅支援24000。speech_ratefloat（可選）音訊語速。1.0為正常語速，小於1.0為慢速，大於1.0為快速。預設值：1.0。取值範圍：[0.5, 2.0]。千問-TTS-Realtime（參見支援的模型）不支援該參數。volumeinteger（可選）音訊音量。預設值：50。取值範圍：[0, 100]。千問-TTS-Realtime（參見支援的模型）不支援該參數。pitch_ratefloat（可選）合成音訊語調。預設值：1.0。取值範圍：[0.5, 2.0]。千問-TTS-Realtime（參見支援的模型）不支援該參數。bit_rateinteger（可選）指定音訊碼率（kbps）。碼率越大，音質越好，音頻檔案體積越大。僅在音頻格式（response_format）為opus時可用。預設值：128。取值範圍：[6, 510]。千問-TTS-Realtime（參見支援的模型）不支援該參數。instructionsstring（可選）設定指令，參見即時語音合成-千問。預設值：無預設值，不設定不生效。長度限制：長度不得超過 1600 Token。支援語言：僅支援中文和英文。適用範圍：該功能僅適用於千問3-TTS-Instruct-Flash-Realtime系列模型。optimize_instructionsboolean（可選）是否對 instructions 進行最佳化，以提升語音合成的自然度和表現力。預設值：false。行為說明：當設定為 true 時，系統將對 instructions 的內容進行語義增強與重寫，產生更適合語音合成的內部指令。適用情境：推薦在追求高品質、精細化語音表達的情境下開啟。依賴關係：此參數依賴於 instructions 參數被設定。如果 instructions 為空白，此參數不生效。適用範圍：該功能僅適用於千問3-TTS-Instruct-Flash-Realtime系列模型。 | {
"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
}
}
|
input_text_buffer.append
用於將待合成文本追加到文本緩衝區。在server_commit模式中，文本將追加到服務端的文本緩衝區；在commit模式中，文本將追加到用戶端的文本緩衝區。
event_idstring（必選）用戶端產生的唯一事件ID。在單次WebSocket串連會話中必須保持唯一。強烈建議使用 UUID（通用唯一識別碼）。typestring（必選）事件類型，固定為input_text_buffer.append。textstring（必選）待合成文本。 | {
"event_id": "event_B4o9RHSTWobB5OQdEHLTo",
"type": "input_text_buffer.append",
"text": "您好，我是千問。"
}
|
input_text_buffer.commit
用於提交使用者輸入文本緩衝區，從而在對話中建立新的使用者訊息項。 如果輸入的文本緩衝區為空白，此事件將產生錯誤。處於“server_commit”模式時，使用者提交此事件，表示立即合成之前的所有文本，伺服器不再緩衝文本。處於“commit”模式時，用戶端必須提交文本緩衝區才能建立使用者訊息項。提交輸入文本緩衝區不會從模型建立響應，伺服器將返回 input_text_buffer.committed 事件進行響應。
event_idstring（必選）用戶端產生的唯一事件ID。在單次WebSocket串連會話中必須保持唯一。強烈建議使用 UUID（通用唯一識別碼）。typestring（必選）事件類型，固定為input_text_buffer.commit。 | {
"event_id": "event_B4o9RHSTWobB5OQdEHLTo",
"type": "input_text_buffer.commit"
}
|
input_text_buffer.clear
用於清除緩衝區中的文本。服務端返回input_text_buffer.cleared 事件進行響應。
event_idstring（必選）用戶端產生的唯一事件ID。在單次WebSocket串連會話中必須保持唯一。強烈建議使用 UUID（通用唯一識別碼）。typestring（必選）事件類型，固定為input_text_buffer.clear。 | {
"event_id": "event_2728",
"type": "input_text_buffer.clear"
}
|
session.finish
用戶端發送 session.finish 事件通知服務端不再有文本輸入，服務端將剩餘音頻返回，隨後關閉串連。
event_idstring（必選）用戶端產生的唯一事件ID。在單次WebSocket串連會話中必須保持唯一。強烈建議使用 UUID（通用唯一識別碼）。typestring（必選）事件類型，固定為session.finish。 | {
"event_id": "event_2239",
"type": "session.finish"
}
|
