Qwen-Audio Realtime API的用戶端事件 - Alibaba Cloud Model Studio

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 和對應的資料欄位。

各 role 支援的 content 類型

system

input_text：系統訊息，必要欄位 text。

user

input_text：使用者文本輸入，必要欄位 text。
input_audio：使用者音頻輸入，必要欄位 audio（Base 64 編碼）。

assistant

output_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"
}