用戶端事件 - Alibaba Cloud Model Studio

相關文檔：即時語音/音視頻翻譯-千問。

session.update

用戶端建立 WebSocket 串連後，需首先發送該事件，用於更新會話的預設配置。服務端收到 session.update 事件後，會校正參數。如果參數不合法，則返回錯誤；如果參數合法，則更新並返回完整的配置。

typestring(必選)事件類型，固定為session.update。sessionobject（可選）會話配置。

屬性

modalitiesarray（可選）模型輸出模態設定，可選值：

["text"] 僅輸出文本。
["text","audio"]（預設值）輸出文本與音頻。

voicestring（可選）產生音訊音色。未啟用聲音複刻時，可設定為系統預設音色，可選值參見支援的音色。Qwen3.5-LiveTranslate-Flash-Realtime預設音色為： Tina。Qwen3-LiveTranslate-Flash-Realtime預設音色為： Cherry。

啟用聲音複刻（enable_voice_clone為true）時，voice的取值取決於frequency：當frequency為once或always時，必須設定為default；當frequency為never時，設定為使用者預先複刻的音色 ID。此時不可設定為系統預設音色，否則服務端會返回錯誤。

enable_voice_cloneboolean（可選）是否啟用聲音複刻。預設值為false。啟用後，模型會基於輸入音頻複刻音色用於翻譯輸出，此時voice不再使用系統預設音色，需設定為default或使用者預先通過聲音複刻API複刻的音色 ID。voice_clone_optionsobject（可選）聲音複刻控制參數，僅在enable_voice_clone為true時生效。

屬性

voice_clone_options.frequencystring（可選）音色複刻頻率，可選值：

never 不在服務端進行音色複刻，使用使用者預先複刻好的音色。此時voice需設定為使用者的複刻音色 ID。
once 會話開始時基於輸入音頻進行一次音色複刻，後續輸出複用該音色。適合單人演講情境。此時voice需設定為default。
always 每次輸出前基於輸入音頻進行即時音色複刻，音色跟隨輸入動態變化。適合多人對話情境。此時voice需設定為default。

sample_rateinteger（可選）輸入音訊採樣率，單位為Hz。可選值：

8000
16000（預設）

input_audio_transcriptionobject（可選）輸入音頻相關配置。

屬性

modelstring（可選）語音辨識模型，預設值為 qwen3-asr-flash-realtime，ASR 預設啟用。服務端會在翻譯的同時返回輸入音訊語音辨識結果（源語言原文），通過conversation.item.input_audio_transcription.text和conversation.item.input_audio_transcription.completed事件返回。如需關閉 ASR，請將此參數顯式設定為 null。可選值：qwen3-asr-flash-realtime（預設，啟用 ASR）、null（關閉 ASR）。languagestring（可選）翻譯源語種，可選值：支援的語種。預設不填寫，此時模型會自動識別源語種。

input_audio_formatstring（可選）使用者輸入音頻格式，可選值：

pcm（預設）未壓縮的原始音頻資料。
opus 有損壓縮音頻編碼，支援低延遲傳輸，適用於網路語音情境。

output_audio_formatstring（可選）輸出音頻格式，當前僅支援設為pcm。turn_detectionobject（可選）語音活動檢測（VAD，Voice Activity Detection）配置，用於控制語音起止的檢測方式：

設為設定物件（預設值）：啟用 VAD 模式。服務端自動檢測語音起止，自動認可音頻緩衝區並觸發翻譯響應，用戶端無需發送input_audio_buffer.commit事件。
設為null：啟用 Manual 模式。由用戶端通過input_audio_buffer.commit事件手動提交音頻緩衝區，服務端收到後自動開始產生翻譯響應。

屬性

typestring（可選）VAD 類型，固定為server_vad。thresholdfloat（可選）VAD 檢測靈敏度。值越低，越容易將微弱聲音（包括背景雜音）識別為語音；值越高，需要更清晰、音量更大的語音才能觸發。取值範圍：[-1.0, 1.0]，預設值為 0.2。silence_duration_msinteger（可選）語音結束後需保持靜音的最短時間長度（毫秒）。超過該時間長度後判定語音結束，服務端自動認可音頻緩衝區並觸發翻譯響應。取值範圍：[200, 6000]，預設值為 1000。

translationobject（可選）翻譯配置。

屬性

languagestring（可選）翻譯目標語種，可選值：支援的語種。預設值為en。same_language_skip_optionsobject（可選）同語種輸出配置。當源語種與目標語種相同時，可跳過文本輸出、音訊輸出或兩者。僅當translation.language為zh或en時生效。

屬性

skip_textboolean（可選）是否在源語種與目標語種相同時跳過文本輸出。skip_audioboolean（可選）是否在源語種與目標語種相同時跳過音訊輸出。

corpusobject（可選）熱詞配置，用於提升特定詞彙的翻譯準確性。

屬性

phrasesobject（可選）熱詞映射表。key 為源語言詞彙，value 為目標語言對應翻譯。樣本：{"人工智慧": "Artificial Intelligence"}

{
  "event_id": "event_ToPZqeobitzUJnt3QqtWg",
  "type": "session.update",
  "session": {
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "Tina",
    "sample_rate": 16000,
    "input_audio_format": "pcm",
    "output_audio_format": "pcm",
    "input_audio_transcription": {
      "model": "qwen3-asr-flash-realtime",
      "language": "zh"
    },
    "translation": {
      "language": "en",
      "corpus": {
        "phrases": {
          "人工智慧": "Artificial Intelligence",
          "機器學習": "Machine Learning"
        }
      }
    }
  }
}

啟用聲音複刻（frequency=once）的樣本：

{
  "event_id": "event_ToPZqeobitzUJnt3QqtWg",
  "type": "session.update",
  "session": {
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "default",
    "enable_voice_clone": true,
    "voice_clone_options": {
      "frequency": "once"
    },
    "sample_rate": 16000,
    "input_audio_format": "pcm",
    "output_audio_format": "pcm",
    "translation": {
      "language": "en"
    }
  }
}

源語種和目標語種均為英語，並跳過文本和音訊輸出的樣本：

{
  "event_id": "event_xxx",
  "type": "session.update",
  "session": {
    "input_audio_transcription": {
      "language": "en"
    },
    "translation": {
      "language": "en",
      "same_language_skip_options": {
        "skip_text": true,
        "skip_audio": true
      }
    }
  }
}

input_audio_buffer.append

向輸入音頻緩衝區追加音頻位元組。服務端使用此緩衝區檢測並決定語音提交時機。

typestring(必選)事件類型，固定為input_audio_buffer.append。audiostring(必選)Base 64 編碼的音頻資料。

{
    "event_id": "event_xxx",
    "type": "input_audio_buffer.append",
    "audio": "xxx"
}

input_audio_buffer.commit

提交輸入音頻緩衝區。僅在 Manual 模式（turn_detection設為null）下需要發送此事件；VAD 模式下服務端會自動認可，用戶端無需發送。服務端收到該事件後，會返回input_audio_buffer.committed事件確認，並自動開始產生翻譯響應（無需再發送其他事件觸發響應）。若音頻緩衝區為空白，服務端將返回錯誤事件。

typestring(必選)事件類型，固定為input_audio_buffer.commit。

{
    "event_id": "event_xxx",
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

清空輸入音頻緩衝區中尚未提交的音頻資料。

typestring(必選)事件類型，固定為input_audio_buffer.clear。

{
    "event_id": "event_xxx",
    "type": "input_audio_buffer.clear"
}

input_image_buffer.append

用於將映像資料添加到映像緩衝區。映像可來自本地檔案，或從視頻流即時採集。目前對圖片輸入有以下限制：

映像格式必須為 JPG 或 JPEG。建議解析度為 480p 或 720p以獲得最佳效能，最高不超過 1080p；
單張圖片大小不大於500KB（Base64編碼前）；
圖片資料需要經過Base64編碼；
以不超過每秒 2 張的頻率向緩衝區添加映像；
發送 input_image_buffer.append 事件前，至少發送過一次 input_audio_buffer.append 事件。

typestring(必選)事件類型，固定為input_image_buffer.append。imagestring(必選）Base 64 編碼的映像資料。

{
    "event_id": "event_xxx",
    "type": "input_image_buffer.append",
    "image": "xxx"
}

session.finish

用於結束當前會話。發送此事件後，服務端響應流程：

已檢測到語音：服務端完成語音辨識後，發送包含識別結果的conversation.item.input_audio_transcription.completed事件，隨後發送session.finished事件作為會話結束標識。
未檢測到語音：服務端直接發送session.finished事件。

用戶端監聽到session.finished事件後，需主動中斷連線。

typestring(必選)事件類型，固定為session.finish。

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

​session.update

​input_audio_buffer.append

​input_audio_buffer.commit

​input_audio_buffer.clear