Skip to main content
即時語音對話

Qwen-Audio 即時語音對話用戶端事件

Qwen-Audio Realtime API的用戶端事件參考。

使用者指南：即時語音對話（Qwen-Audio-Realtime）。如需瞭解事件互動時序，請參見WebSocket API。

session.update

說明：建立串連後，發送此事件更新會話的預設配置。僅包含需要變更的欄位，未傳欄位保持原值。服務端收到後校正參數，若參數不合法則返回錯誤，若參數合法則應用更改並返回完整配置。
turn_detection 僅在首次發送音頻之前（IDLE 狀態）允許修改。
typestring（必選）事件類型，固定為 session.update。sessionobject（可選）會話配置。

屬性

modalitiesarray（可選）模型輸出模態設定，可選值：
  • ["text"] 僅輸出文本。
  • ["audio", "text"]（預設值） 同時輸出文本和音頻。
voicestring（可選）TTS 音色名稱，預設值為 longanqian。支援兩種類型，僅可在第一次 session.update 中設定，後續傳入將被忽略。
  • 系統音色：可選值：longanqian、longanlingxin、longanlingxi、longanxiaoxin、longanlufeng。
  • 聲音複刻音色：通過聲音複刻 API 建立，將返回的 voice_id 填入此參數。詳見音色配置。
enable_speech_emotionboolean（可選）是否開啟情緒增強功能。開啟後，回複音色的情緒變化更明顯。預設值：true。可選值：true、false。instructionsstring（可選）系統指令，用於設定模型的角色身份、回答風格和行為偏好。對整個會話生效。input_audio_formatstring（可選）輸入音頻格式。當前僅支援 pcm（16kHz 16bit 單聲道），為預設值。僅在首次發送音頻之前（IDLE 狀態）允許修改。output_audio_formatstring（可選）輸出音頻格式。當前僅支援 pcm（24kHz 16bit 單聲道），為預設值。max_history_turnsinteger（可選）允許單次請求的最大歷史 QA 輪數。取值範圍為 1-50，預設值為 20。toolsarray（可選）Function Calling 工具定義列表。配置後模型可根據使用者輸入自主決定是否調用工具。
typestring（必選）固定為 function。function.namestring（必選）工具函數名稱。function.descriptionstring（可選）對工具函數功能的描述，模型據此判斷是否調用該工具。function.parametersobject（可選）對工具函數入參的描述，模型據此提取所需入參。若函數無需入參，可不指定。
typestring（必選）固定為 object。propertiesobject（可選）描述各入參的名稱、資料類型與說明。requiredarray（可選）指定哪些入參為必填項。
turn_detectionobject|null（可選）輪次檢測配置。設為 null 可切換為 push-to-talk 模式（手動提交音頻並觸發推理）。若不提供此欄位，系統將使用預設參數啟用 VAD。
typestring（可選）VAD 類型，可選值：
  • server_vad（預設值）：基於聲學特徵檢測語音起止，自動觸發推理。
  • smart_turn：融合聲學感知與語義理解的智能輪次檢測，通過聲學與語義雙重判斷輪次邊界。無語義的聲音（如”嗯”、”啊”）不會觸發對話輪或打斷模型播報。
thresholdfloat（可選）VAD靈敏度，僅在 server_vad 模式下生效（smart_turn 模式下無效）。值越低，VAD越靈敏，越容易將微弱聲音（包括背景雜音）識別為語音；值越高，越不靈敏，需要更清晰、音量更大的語音才能觸發。取值範圍為[-1.0, 1.0]，預設值為 0.5。silence_duration_msinteger（可選）語音結束後需保持靜音的最短時間（毫秒），僅在 server_vad 模式下生效（smart_turn 模式下無效）。逾時即觸發模型響應。值越低，響應越快，但可能在短暫停頓時誤觸發。取值範圍為[200, 6000]，預設值為 800。對話情境推薦 400-800。voiceprint_audio_urlsarray（可選）僅在 smart_turn 模式下生效。目標使用者預錄音訊公網可存取 URL 列表，用於說話人增強。傳入後，模型將在雙工對話中精準鎖定目標說話人，有效忽略旁人聲音與背景雜訊。最多支援 5 個 URL。音頻格式要求：16kHz PCM 或 WAV。
該參數僅在第一次發送 session.update 事件時可配置，後續傳入該欄位將被忽略。
{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian",
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}
Function Calling：
{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "查詢指定城市天氣",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "city": {
                                "type": "string",
                                "title": "城市"
                            }
                        },
                        "required": ["city"]
                    }
                }
            }
        ],
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}
聲紋註冊（voiceprint_audio_urls）：
{
    "type": "session.update",
    "session": {
        "turn_detection": {
            "type": "smart_turn",
            "voiceprint_audio_urls": [
                "https://example.com/speaker1.pcm",
                "https://example.com/speaker2.wav"
            ]
        }
    }
}

input_audio_buffer.append

說明：追加音頻資料到輸入緩衝區。應持續、高頻發送（如每 20~40 ms 一幀）。此事件無服務端確認回包。
typestring（必選）事件類型，固定為 input_audio_buffer.append。audiostring（必選）Base 64 編碼的音頻資料。
{
    "type": "input_audio_buffer.append",
    "audio": "<base64 編碼的音頻資料>"
}

input_audio_buffer.commit

說明：僅 push-to-talk 模式。將緩衝區音頻提交為一條使用者訊息。提交後不會自動觸發推理，需要發送 response.create 手動觸發。 server_vad / smart_turn 模式下此事件被忽略。
typestring（必選）事件類型，固定為 input_audio_buffer.commit。
{
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

說明：僅 push-to-talk 模式。清空緩衝區中尚未提交的音頻。server_vad / smart_turn 模式下此事件被忽略。服務端以 input_audio_buffer.cleared 事件響應。
typestring（必選）事件類型，固定為 input_audio_buffer.clear。
{
    "type": "input_audio_buffer.clear"
}

conversation.item.create

說明：手動向對話上下文插入一條對話項。可用於注入歷史上下文、補充文本資訊，或寫回 Function Calling 的工具執行結果。
若 item.id 已存在於對話中，會返回錯誤並拒絕建立。
typestring（必選）事件類型，固定為 conversation.item.create。previous_item_idstring（可選）指定新項插入到哪條對話項之後。不傳時追加到對話末尾。itemobject（必選）要建立的對話項。

屬性

idstring（可選）對話項的唯一識別碼。不傳時由服務端自動產生。若指定的 ID 已存在於對話中，會返回錯誤。typestring（必選）對話項類型，可選值：
  • message：普通對話訊息。
  • function_call：函數調用請求。通常由服務端產生，用戶端也可用於補充歷史上下文。
  • function_call_output：工具執行結果。用戶端收到 function_call 後執行工具，並用該類型寫回結果。
rolestring（message 類型必選）訊息角色，可選值：system、user、assistant。contentarray（message 類型必選）訊息內容列表。每個元素包含 type 和對應的資料欄位。
systeminput_text：系統訊息，必要欄位 text。user
  • input_text：使用者文本輸入，必要欄位 text。
  • input_audio：使用者音頻輸入，必要欄位 audio（Base 64 編碼）。
assistantoutput_text：助手文本輸出，必要欄位 text。
call_idstring（function_call / function_call_output 類型必選）函數調用的唯一識別碼，用於關聯請求和結果。namestring（function_call 類型必選）要調用的函數名稱。argumentsstring（function_call 類型必選）函數調用參數，JSON 字串格式。outputstring（function_call_output 類型必選）工具執行結果，JSON 字串格式。
注入使用者簡訊：
{
    "type": "conversation.item.create",
    "previous_item_id": "item_xxx",
    "item": {
        "id": "my_item_001",
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "請幫我總結一下上次的對話"
            }
        ]
    }
}
寫回 Function Calling 結果：
{
    "type": "conversation.item.create",
    "item": {
        "type": "function_call_output",
        "call_id": "call_xxx",
        "output": "{\"temperature\":18,\"condition\":\"晴\"}"
    }
}

conversation.item.retrieve

說明：查詢服務端儲存的某條對話項。返回的音訊類型 content 僅包含轉寫文本（transcript），不包含原始音頻資料。
typestring（必選）事件類型，固定為 conversation.item.retrieve。item_idstring（必選）要查詢的對話項 ID。服務端以 conversation.item.retrieved 事件返回查詢結果。
{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}

conversation.item.delete

說明：從對話上下文中刪除指定對話項。服務端以 conversation.item.deleted 事件確認。
typestring（必選）事件類型，固定為 conversation.item.delete。item_idstring（必選）要刪除的對話項 ID。
{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

response.create

說明：顯式觸發一次模型推理。各模式下的行為如下：
  • push-to-talk 模式：必須手動調用，需先通過 input_audio_buffer.commit 提交緩衝區音頻或寫入 function_call_output 後觸發。當前有響應正在產生時不允許重複觸發。
  • server_vad 模式：通常由服務端自動觸發。當前無響應正在產生時，用戶端也允許手動調用；有響應正在產生時不允許重複觸發。
  • smart_turn 模式：等待使用者下一輪輸入時允許調用。當前處於一個 turn 內時（收到 input_audio_buffer.speech_started 到 response.done 期間）不允許重複觸發。
response 欄位可選，用於覆蓋本輪推理的會話預設配置。Function Calling 情境下，用戶端寫入 function_call_output 後也通過該事件觸發二輪推理。
server_vad / smart_turn 模式下，手動觸發的推理仍可能被新語音打斷。
typestring（必選）事件類型，固定為 response.create。responseobject（可選）用於覆蓋本輪推理的會話預設配置。不傳時使用當前會話配置。
modalitiesarray（可選）覆蓋本輪的輸出模態設定。可選值與 session.update 中的 modalities 一致。voicestring（可選）覆蓋本輪的 TTS 音色。
{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

response.cancel

說明：取消當前進行中的推理。已輸出的部分文本會寫入 item 鏈表，服務端返回 status=cancelled 的 response.done。 若當前無進行中的推理，返回錯誤。
typestring（必選）事件類型，固定為 response.cancel。
{
    "type": "response.cancel"
}
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
  • 概述
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多