使用者指南：即時語音對話（Qwen-Audio-Realtime）。如需瞭解事件互動時序，請參見WebSocket API。
session.update
說明：建立串連後，發送此事件更新會話的預設配置。僅包含需要變更的欄位，未傳欄位保持原值。服務端收到後校正參數，若參數不合法則返回錯誤，若參數合法則應用更改並返回完整配置。
說明
turn_detection 僅在首次發送音頻之前（IDLE 狀態）允許修改。
|
type string（必選）
事件類型，固定為 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"
]
}
}
}
|
|
session object（可選）
會話配置。
屬性
modalities array（可選）
模型輸出模態設定，可選值：
-
["text"]
僅輸出文本。
-
["audio", "text"]（預設值）
同時輸出文本和音頻。
voice string（可選）
TTS 音色名稱，預設值為 longanqian。支援兩種類型，僅可在第一次 session.update 中設定，後續傳入將被忽略。
instructions string（可選）
系統指令，用於設定模型的角色身份、回答風格和行為偏好。對整個會話生效。
input_audio_format string（可選）
輸入音頻格式。當前僅支援 pcm（16kHz 16bit 單聲道），為預設值。僅在首次發送音頻之前（IDLE 狀態）允許修改。
output_audio_format string（可選）
輸出音頻格式。當前僅支援 pcm（24kHz 16bit 單聲道），為預設值。
max_history_turns integer（可選）
允許單次請求的最大歷史 QA 輪數。取值範圍為 1-50，預設值為 20。
tools array（可選）
Function Calling 工具定義列表。配置後模型可根據使用者輸入自主決定是否調用工具。
屬性
type string（必選）
固定為 function。
function.name string（必選）
工具函數名稱。
function.description string（可選）
對工具函數功能的描述，模型據此判斷是否調用該工具。
function.parameters object（可選）
對工具函數入參的描述，模型據此提取所需入參。若函數無需入參，可不指定。
屬性
type string（必選）
固定為 object。
properties object（可選）
描述各入參的名稱、資料類型與說明。
required array（可選）
指定哪些入參為必填項。
turn_detection object|null（可選）
輪次檢測配置。設為 null 可切換為 push-to-talk 模式（手動提交音頻並觸發推理）。若不提供此欄位，系統將使用預設參數啟用 VAD。
屬性
type string（可選）
VAD 類型，可選值：
threshold float（可選）
VAD靈敏度，僅在 server_vad 模式下生效（smart_turn 模式下無效）。值越低，VAD越靈敏，越容易將微弱聲音（包括背景雜音）識別為語音；值越高，越不靈敏，需要更清晰、音量更大的語音才能觸發。
取值範圍為[-1.0, 1.0]，預設值為 0.5。
silence_duration_ms integer（可選）
語音結束後需保持靜音的最短時間（毫秒），僅在 server_vad 模式下生效（smart_turn 模式下無效）。逾時即觸發模型響應。值越低，響應越快，但可能在短暫停頓時誤觸發。
取值範圍為[200, 6000]，預設值為 800。對話情境推薦 400-800。
voiceprint_audio_urls array（可選）
僅在 smart_turn 模式下生效。目標使用者預錄音訊公網可存取 URL 列表，用於說話人增強。傳入後，模型將在雙工對話中精準鎖定目標說話人，有效忽略旁人聲音與背景雜訊。最多支援 5 個 URL。音頻格式要求：16kHz PCM 或 WAV。
重要
該參數僅在第一次發送 session.update 事件時可配置，後續傳入該欄位將被忽略。
|
input_audio_buffer.append
說明：追加音頻資料到輸入緩衝區。應持續、高頻發送（如每 20~40 ms 一幀）。此事件無服務端確認回包。
|
type string（必選）
事件類型，固定為 input_audio_buffer.append。
|
{
"type": "input_audio_buffer.append",
"audio": "<base64 編碼的音頻資料>"
}
|
|
audio string（必選）
Base 64 編碼的音頻資料。
|
input_audio_buffer.commit
說明：僅 push-to-talk 模式。將緩衝區音頻提交為一條使用者訊息。提交後不會自動觸發推理，需要發送 response.create 手動觸發。
server_vad / smart_turn 模式下此事件被忽略。
|
type string（必選）
事件類型，固定為 input_audio_buffer.commit。
|
{
"type": "input_audio_buffer.commit"
}
|
input_audio_buffer.clear
說明：僅 push-to-talk 模式。清空緩衝區中尚未提交的音頻。server_vad / smart_turn 模式下此事件被忽略。服務端以 input_audio_buffer.cleared 事件響應。
|
type string（必選）
事件類型，固定為 input_audio_buffer.clear。
|
{
"type": "input_audio_buffer.clear"
}
|
conversation.item.create
說明：手動向對話上下文插入一條對話項。可用於注入歷史上下文、補充文本資訊，或寫回 Function Calling 的工具執行結果。
說明
若 item.id 已存在於對話中，會返回錯誤並拒絕建立。
|
type string（必選）
事件類型，固定為 conversation.item.create。
|
注入使用者簡訊： {
"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\":\"晴\"}"
}
}
|
|
previous_item_id string（可選）
指定新項插入到哪條對話項之後。不傳時追加到對話末尾。
|
|
item object（必選）
要建立的對話項。
屬性
id string（可選）
對話項的唯一識別碼。不傳時由服務端自動產生。若指定的 ID 已存在於對話中，會返回錯誤。
type string（必選）
對話項類型，可選值：
role string（message 類型必選）
訊息角色，可選值：system、user、assistant。
content array（message 類型必選）
訊息內容列表。每個元素包含 type 和對應的資料欄位。
各 role 支援的 content 類型
system
input_text：系統訊息，必要欄位 text。
assistant
output_text：助手文本輸出，必要欄位 text。
call_id string（function_call / function_call_output 類型必選）
函數調用的唯一識別碼，用於關聯請求和結果。
name string（function_call 類型必選）
要調用的函數名稱。
arguments string（function_call 類型必選）
函數調用參數，JSON 字串格式。
output string（function_call_output 類型必選）
工具執行結果，JSON 字串格式。
|
conversation.item.retrieve
說明：查詢服務端儲存的某條對話項。返回的音訊類型 content 僅包含轉寫文本（transcript），不包含原始音頻資料。
|
type string（必選）
事件類型，固定為 conversation.item.retrieve。
|
{
"type": "conversation.item.retrieve",
"item_id": "item_xxx"
}
|
|
item_id string（必選）
要查詢的對話項 ID。服務端以 conversation.item.retrieved 事件返回查詢結果。
|
conversation.item.delete
說明：從對話上下文中刪除指定對話項。服務端以 conversation.item.deleted 事件確認。
|
type string（必選）
事件類型，固定為 conversation.item.delete。
|
{
"type": "conversation.item.delete",
"item_id": "item_xxx"
}
|
|
item_id string（必選）
要刪除的對話項 ID。
|
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 模式下，手動觸發的推理仍可能被新語音打斷。
|
type string（必選）
事件類型，固定為 response.create。
|
{
"type": "response.create",
"response": {
"modalities": ["audio", "text"]
}
}
|
|
response object（可選）
用於覆蓋本輪推理的會話預設配置。不傳時使用當前會話配置。
屬性
modalities array（可選）
覆蓋本輪的輸出模態設定。可選值與 session.update 中的 modalities 一致。
voice string（可選）
覆蓋本輪的 TTS 音色。
|
response.cancel
說明：取消當前進行中的推理。已輸出的部分文本會寫入 item 鏈表，服務端返回 status=cancelled 的 response.done。
若當前無進行中的推理，返回錯誤。
|
type string（必選）
事件類型，固定為 response.cancel。
|
{
"type": "response.cancel"
}
|