Alibaba Cloud Model Studio：Qwen-Audio-3.0-Realtime 即時語音對話 iOS SDK

url

String

是

服務位址：

• wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
• 華北 2（北京）：wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
• 新加坡：wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>

apikey

String

是

API Key。

service_mode

String

是

執行模式。即時語音對話固定為 "1"。

device_id

String

是

用於識別終端使用者的唯一字串，可設為應用程式內使用者 ID 或用戶端產生的裝置唯一識別碼。此 ID 主要用於日誌追蹤和問題排查。

audio_update_manually

String

否

是否啟用主動推送音訊資料模式，預設值："false"。
當設定為 "true" 啟用主動推送音訊資料模式時，且 SDK 版本支援端側音訊能力（如 AEC、VAD），則預設開啟端側音訊能力。

workspace

String

否

端側資源檔案的儲存路徑。當 audio_update_manually 設為 "true" 且啟用端側音訊能力（如 AEC、VAD）時，必須設定此參數。

debug_path

String

否

日誌檔案的儲存路徑。此參數僅在呼叫nui_initialize介面時將save_log設為YES時生效。此時必須設定日誌檔案路徑，否則將報錯。本機最多保留兩個日誌檔案。

save_wav

String

否

是否儲存偵錯用的音訊檔案。音訊檔案儲存於debug_path下。預設值："false"。
取值範圍：

• "true"：是
• "false"：否

max_log_file_size

int

否

設定日誌檔案的最大位元組數。此參數僅在呼叫nui_initialize介面時將save_log設為YES時生效。預設值：104857600（100 × 1024 × 1024 位元組，即 100MiB）。

log_track_level

int

否

控制透過日誌回呼（onNuiLogTrackCallback）對外傳送的日誌內容的過濾層級。
預設值：2。
取值範圍：

• 0：LOG_LEVEL_VERBOSE
• 1：LOG_LEVEL_DEBUG
• 2：LOG_LEVEL_INFO
• 3：LOG_LEVEL_WARNING
• 4：LOG_LEVEL_ERROR
• 5：LOG_LEVEL_NONE（表示關閉此功能）

service_type

int

是

語音服務類型。即時語音對話固定為 4。

nls_config

object

是

語音對話核心設定物件，包含模型選擇、對話效果控制等關鍵參數。

nls_config.model

string

是

指定模型名稱。支援 qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus 和 qwen-audio-3.0-realtime-flash 系列模型。

nls_config.sr_format

string

是

輸入音訊格式。目前僅支援 pcm（16kHz 16bit 單聲道），為預設值。

nls_config.modalities

string

否

array 格式的字串，模型輸出模態設定，可選值：

• ["text"]：僅輸出文字。
• ["audio", "text"]（預設值）：同時輸出文字和音訊。

nls_config.voice

string

否

TTS 音色名稱，3.1 Plus 的預設值為 longanqian_v3.1，3.0 Plus/Flash 的預設值為 longanqian。支援兩種類型，僅可在第一次 session.update 中設定，後續傳入將被忽略。

• 系統音色：可選值：longanqian、longanlingxin、longanlingxi、longanxiaoxin、longanlufeng。
• 聲音複製音色：透過聲音複製 API 建立，將傳回的 voice_id 填入此參數。詳見音色設定。

3.1 Plus 還支援 longanqian_v3.1、longanhuan_v3.1、longanlingxin_v3.1、longanfengyue_v3.1、xunanchuan_v3.1、beth_v3.1、betty_v3.1、cally_v3.1。

nls_config.enable_speech_emotion

BOOL

否

是否開啟情緒增強功能。開啟後，回覆音色的情緒變化更明顯。預設值：YES。可選值：YES、NO。

nls_config.instructions

string

否

系統指令，用於設定模型的角色身分、回答風格和行為偏好。對整個對話生效。

nls_config.max_history_turns

int

否

允許單次請求的最大歷史 QA 輪數。取值範圍為 1-50，預設值為 20。

nls_config.tools

string

否

array 格式的字串。Function Calling 工具定義清單。設定後模型可根據使用者輸入自主決定是否呼叫工具。
內部參數說明：
typestring（必選）
固定為 function。
function.namestring（必選）
工具函數名稱。
function.descriptionstring（選填）
對工具函數功能的描述，模型據此判斷是否呼叫該工具。
function.parametersobject（選填）
對工具函數輸入參數的描述，模型據此提取所需輸入參數。若函數無需輸入參數，可不指定。
範例：

[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "查询指定城市的天气信息。",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "城市"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  }
]

nls_config.turn_detection

string

否

JSON 物件形式的字串。輪次偵測設定。未設定時則切換為 push-to-talk 模式（手動提交音訊並觸發推理）。否則啟用雙工對話模式。

nls_config.turn_detection.type

string

否

VAD 類型，可選值：

• server_vad（預設值）：基於聲學特徵偵測語音起止，自動觸發推理。
• smart_turn：融合聲學感知與語意理解的智慧輪次偵測，透過聲學與語意雙重判斷輪次邊界。無語意的聲音（如「嗯」、「啊」）不會觸發對話輪或打斷模型播報。

nls_config.turn_detection.threshold

float

否

VAD 靈敏度，僅在 server_vad 模式下生效（smart_turn 模式下無效）。值越低，VAD 越靈敏，越容易將微弱聲音（包括背景雜訊）識別為語音；值越高，越不靈敏，需要更清晰、音量更大的語音才能觸發。
取值範圍為 [-1.0, 1.0]，預設值為 0.5。

nls_config.turn_detection.silence_duration_ms

int

否

語音結束後需保持靜音的最短時間（毫秒），僅在 server_vad 模式下生效（smart_turn 模式下無效）。逾時即觸發模型回應。值越低，回應越快，但可能在短暫停顿時誤觸發。
取值範圍為 [200, 6000]，預設值為 800。對話場景推薦 400-800。

nls_config.turn_detection.voiceprint_audio_urls

string

否

array 形式的字串。僅在 smart_turn 模式下生效。目標使用者預錄音訊的公網可存取 URL 清單，用於說話人增強。傳入後，模型將在雙工對話中精準鎖定目標說話人，有效忽略旁人聲音與背景雜訊。最多支援 5 個 URL。音訊格式要求：16kHz PCM 或 WAV。

parameters

char*

JSON 字串，包含驗證、連線和偵錯參數。請參見連線與控制參數。

level

NuiSdkLogLevel

控制 SDK 自身日誌的列印層級。

save_log

BOOL

是否儲存本機日誌。若為YES，須在連線與控制參數透過debug_path指定路徑，並可透過max_log_file_size設定檔案大小。

params

char*

語音對話效果參數。

vad_mode

NuiVadMode

VAD 模式。固定為 MODE_P2T。

dialog_params

char*

如果 連線與控制參數 的 apikey 參數使用的是 臨時 API Key，當其過期時，可在此處進行更新。
內容為 JSON 格式：

{
  "apikey": "st-****"
}

force

BOOL

是否強制結束而忽略最終結果。

• YES：不等待伺服器返回最終辨識結果就立即結束任務。
• NO：結束任務，但是會等待完整結果返回。

params

char*

JSON 字串，用於更新對話上下文等執行時行為。

params.type

String

固定為 "action"。

params.command

String

具體的執行指令，當前支援 function_call、play_start、play_over。

• function_call：更新函數呼叫請求的指令。
• play_start：當使用端側 AEC 時，透過此指令通知 SDK 內部 AEC 播放器開始播放音訊。
• play_over：當使用端側 AEC 時，透過此指令通知 SDK 內部 AEC 播放器已經播放結束。

params.context

String

當 command 為 "function_call" 時，更新函數呼叫請求。

params.context.type

String

事件類型，當command為"function_call"時必須設定。

• conversation.item.create：手動向對話上下文插入一條對話項目。可用於注入歷史上下文、補充文字資訊，或寫回 Function Calling 的工具執行結果。
• response.create：在 conversation.item.create 指令傳送後，透過此指令觸發第二輪推理。

params.context.item

object

params.context.type 為 conversation.item.create 時必須設定，表示要建立的對話項目。詳見如下。

params.context.response

object

params.context.type 為 response.create 時可設定，表示用於覆蓋本輪推理的工作階段預設設定。未傳送時使用目前工作階段設定。詳見如下。

id

String

選填。對話項目的唯一識別碼。未傳送時由伺服器端自動產生。若指定的 ID 已存在於對話中，會傳回錯誤。

type

String

必選。對話項類型，可選值：

• message：一般對話訊息。
• function_call：函數呼叫請求。通常由伺服器端產生，用戶端也可用於補充歷史上下文。
• function_call_output：工具執行結果。用戶端收到 function_call 後執行工具，並用該類型寫回結果。

role

String

message 類型必選。訊息角色，可選值：system、user、assistant。

content

array

message 類型必選。訊息內容清單。每個元素包含 type 和對應的資料欄位。
各 role 支援的 content 類型：
system
input_text：系統訊息，必填欄位 text。
user

• input_text：使用者文字輸入，必填欄位 text。
• input_audio：使用者音訊輸入，必填欄位 audio（Base64 編碼）。

call_id

String

（function_call / function_call_output 類型必選）
函數呼叫的唯一識別碼，用於關聯請求和結果。

name

String

（function_call 類型必選）
要呼叫的函數名稱。

arguments

String

function_call 類型必選）
函數呼叫參數，JSON 字串格式。

output

String

（function_call_output 類型必選）
工具執行結果，JSON 字串格式。

modalities

array

array 格式的字串，模型輸出模態設定，可選值：

• ["text"]：僅輸出文字。
• ["audio", "text"]（預設值）：同時輸出文字和音訊。

voice

string

覆蓋本輪的 TTS 音色。

data

const char *

推送的音訊資料。

length

int

推送的音訊資料的位元組數。

first_pack

BOOL

無需關注此參數。

data

const char *

推送的音訊資料。

length

int

推送的音訊資料的位元組數。

first_pack

BOOL

無需關注此參數。

nuiEvent

NuiCallbackEvent

回調事件。

dialog

long

會話編碼，無需關注該參數。

wuw

char*

語音喚醒功能。無需關注此參數。

asr_result

char*

語音辨識結果。

finish

BOOL

本輪辨識是否結束標誌。

code

int

僅在出現 EVENT_ASR_ERROR 事件時有效。

STATE_OPEN

互動啟動，可以開啟錄音裝置進行錄音。

STATE_PAUSE

互動停止，可以停止錄音。

STATE_CLOSE

SDK 執行個體已釋放，可以徹底關閉錄音裝置。

audioData

char *

填入的音訊資料。

len

int

填入的音訊資料的位元組數。

nuiEvent

NuiCallbackEvent

回調事件。

info

char *

無需關注此參數。

info_len

int

無需關注此參數。

buffer

char *

輔助資料，例如 AI 返回的 TTS 音訊。

len

int

輔助資料的位元組數。

EVENT_TRANSCRIBER_STARTED

任務啟動成功。

EVENT_VAD_START

任務啟動後即觸發此事件。不代表偵測到人聲起點。

EVENT_VAD_END

偵測到人聲終點。

EVENT_ASR_PARTIAL_RESULT

語音辨識中間結果。

EVENT_ASR_ERROR

語音對話過程中發生錯誤。

EVENT_MIC_ERROR

因連續 2 秒未收到任何音訊資料而觸發。

EVENT_SENTENCE_END

偵測到一句話結束，此時會返回一句完整的辨識結果。

EVENT_TRANSCRIBER_COMPLETE

語音對話結束。

EVENT_AUDIO_TRANSCRIPTION

音訊模式下的文字字幕增量事件，串流返回字幕片段。

EVENT_AUDIO_TRANSCRIPTION_COMPLETED

音訊模式下的字幕輸出完成事件。

EVENT_OTHER_RESULT

其他未歸類事件資訊，例如 function_call 的返回結果等。

EVENT_ASR_TTS_START

AI 開始返回 TTS 資料。

EVENT_ASR_TTS_DATA

AI 返回的 TTS 資料。

EVENT_ASR_TTS_COMPLETE

AI 返回 TTS 資料結束。

EVENT_AEC_DATA

AEC 回音消除後的音訊資料。