Skip to main content
Qwen-Audio-Realtime

SDK iOS percakapan suara real-time Qwen-Audio-3.0-Realtime

Gunakan iOS SDK untuk Qwen-Audio-3.0-Realtime guna membangun percakapan suara real-time dengan input audio dan output audio atau teks.

Panduan pengguna: Untuk pengenalan model dan saran pemilihan, lihat Percakapan suara real-time.

Mulai cepat

  1. Dapatkan API key: Dapatkan dan konfigurasikan API key.
  2. Unduh SDK dan jalankan kode contoh:
    • Unduh paket SDK terbaru.
    • Ekstrak paket ZIP dan tambahkan nuisdk.xcframework ke proyek Anda.
    • Di Build Phases > Link Binary With Libraries, tambahkan nuisdk.xcframework.
    • Di General > Frameworks, Libraries, and Embedded Content, atur nuisdk.xcframework ke Embed & Sign.
    • Buka proyek di Xcode. Kode contoh ada di DashQwenAudioChatViewController.m. Ganti API key untuk mencoba fitur ini.

Prosedur pemanggilan

  1. Inisialisasi SDK.
  2. Atur parameter untuk kasus penggunaan Anda. Gunakan argumen parameters dari nui_initialize untuk mengatur connection and control parameters, dan gunakan nui_set_params untuk mengatur voice conversation parameters.
  3. Panggil nui_dialog_start untuk memulai percakapan.
  4. Di onNuiAudioStateChanged, mulai perangkat perekaman berdasarkan status audio.
  5. Pasok data rekaman secara terus-menerus di onNuiNeedAudioData, atau panggil nui_update_audio_data untuk mendorong data rekaman secara aktif.
  6. Terima secara terus-menerus audio yang dikembalikan oleh model di onNuiAssistEventCallback.
  7. Dengarkan event dan dapatkan informasi event di onNuiEventCallback.
  8. Panggil nui_dialog_cancel untuk menghentikan percakapan, dan dengarkan EVENT_TRANSCRIBER_COMPLETE untuk mengonfirmasi bahwa percakapan telah berakhir.
  9. Ketika fitur percakapan tidak lagi diperlukan, panggil nui_release untuk melepaskan sumber daya SDK.

Parameter permintaan

Parameter koneksi dan kontrol

Berikan string JSON dalam argumen parameters dari nui_initialize. Contoh: String JSON berikut tidak mencantumkan setiap parameter. Tambahkan parameter sesuai kebutuhan untuk kasus penggunaan Anda.
{
  "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id",
  "service_mode": "1"
}
Parameter
ParameterTipeWajibDeskripsi
urlStringYaEndpoint layanan:
  • wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Tiongkok (Beijing): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
Ganti {WorkspaceId} dengan ID Workspace.
apikeyStringYaAPI key.
service_modeStringYaMode runtime. Atur parameter ini ke "1" untuk percakapan suara real-time.
device_idStringYaString unik yang mengidentifikasi pengguna akhir. Anda dapat menggunakan ID pengguna dalam aplikasi atau pengidentifikasi perangkat yang dibuat klien. ID ini terutama digunakan untuk pelacakan log dan pemecahan masalah.
audio_update_manuallyStringTidakApakah akan mendorong data audio secara aktif. Default: "false". Jika diatur ke "true" dan SDK mendukung kemampuan audio on-device seperti AEC dan VAD, kemampuan tersebut diaktifkan secara default.
workspaceStringTidakJalur penyimpanan untuk file sumber daya on-device. Parameter ini wajib diisi jika audio_update_manually adalah "true" dan kemampuan audio on-device seperti AEC atau VAD diaktifkan.
debug_pathStringTidakJalur penyimpanan file log. Parameter ini hanya berlaku jika save_log adalah true di nui_initialize. Dalam hal ini, jalur wajib diisi. SDK menyimpan paling banyak dua file log secara lokal.
save_wavStringTidakApakah akan menyimpan audio debug di bawah debug_path. Default: "false". Nilai yang valid adalah "true" dan "false". Parameter ini hanya berlaku jika save_log adalah true, dan debug_path juga harus diatur.
max_log_file_sizeintTidakUkuran file log maksimum dalam byte. Parameter ini hanya berlaku jika save_log adalah true. Default: 104857600 (100 × 1024 × 1024 byte, atau 100 MiB).
log_track_levelintTidakTingkat filter untuk log yang dikirim melalui onNuiLogTrackCallback. Default: 2. Nilai yang valid: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR), dan 5 (NONE). Log hanya dikembalikan jika tingkatnya lebih besar dari atau sama dengan log_track_level dan level yang diteruskan ke nui_initialize. Misalnya, jika log_track_level adalah 2 (INFO) dan level adalah 3 (WARNING), hanya log WARNING dan tingkat lebih tinggi (nilai lebih besar dari atau sama dengan 3) yang dikembalikan.

Parameter percakapan suara

Berikan string JSON dalam argumen params dari nui_set_params. Contoh: String JSON berikut tidak mencantumkan setiap parameter. Tambahkan parameter sesuai kebutuhan untuk kasus penggunaan Anda.
{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm"
  }
}
Parameter
Parameter tingkat atasTipeWajibDeskripsi
service_typeintYaTipe layanan suara. Atur parameter ini ke 4 untuk percakapan suara real-time.
nls_configobjectYaKonfigurasi inti percakapan suara, termasuk pemilihan model dan perilaku percakapan.
nls_config.modelstringYaNama model. Mendukung seri model qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash.
nls_config.sr_formatstringYaFormat audio input. Hanya pcm yang didukung. Format defaultnya adalah PCM mono 16 kHz, 16-bit.
nls_config.modalitiesstringTidakString yang berisi array modalitas output. Nilai yang valid:
  • ["text"]: hanya mengembalikan teks.
  • ["audio", "text"] (default): mengembalikan audio dan teks.
nls_config.voicestringTidakSuara TTS. Defaultnya adalah longanqian_v3.1 untuk 3.1 Plus dan longanqian untuk 3.0 Plus/Flash. Parameter ini hanya dapat diatur pada session.update pertama; nilai berikutnya akan diabaikan. Suara sistem: longanqian, longanlingxin, longanlingxi, longanxiaoxin, dan longanlufeng. Anda juga dapat menentukan voice_id kloning yang dibuat melalui API kloning suara. Lihat Konfigurasi suara.3.1 Plus juga mendukung 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_emotionBOOLTidakApakah akan mengaktifkan ekspresi emosional yang ditingkatkan. Saat diaktifkan, suara respons memiliki variasi emosional yang lebih kentara. Default: YES. Nilai yang valid: YES dan NO.
nls_config.instructionsstringTidakInstruksi sistem yang menentukan peran model, gaya respons, dan preferensi perilaku untuk seluruh sesi.
nls_config.max_history_turnsintTidakJumlah maksimum giliran tanya-jawab historis yang diizinkan dalam satu permintaan. Nilai yang valid: 1 hingga 50. Default: 20.
nls_config.toolsstringTidakString yang berisi array definisi alat Function Calling. Setelah Anda mengonfigurasi parameter ini, model memutuskan apakah akan memanggil alat berdasarkan input pengguna. Setiap definisi menggunakan type (wajib dan ditetapkan ke function) dan objek function yang berisi name (wajib), description (opsional), dan parameters (opsional). Jika fungsi tidak memiliki argumen, abaikan parameters.
Contoh:
[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Queries weather information for a specified city.",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  }
]
nls_config.turn_detectionstringTidakString yang berisi objek JSON untuk deteksi giliran. Jika diabaikan, sesi menggunakan mode push-to-talk, di mana audio dikirim dan inferensi dipicu secara manual. Jika diatur, mode percakapan dupleks diaktifkan.
nls_config.turn_detection.typestringTidakTipe VAD. server_vad (default) mendeteksi batasan ucapan dari fitur akustik dan secara otomatis memicu inferensi. smart_turn menggabungkan sinyal akustik dan semantik; suara tanpa konten semantik, seperti suara pengisi, tidak memulai giliran atau mengganggu pemutaran model.
nls_config.turn_detection.thresholdfloatTidakSensitivitas VAD. Parameter ini hanya berlaku untuk server_vad dan tidak berpengaruh pada smart_turn. Nilai yang lebih rendah membuat VAD lebih sensitif terhadap suara pelan dan kebisingan latar belakang; nilai yang lebih tinggi memerlukan ucapan yang lebih jelas dan lebih keras. Rentang yang valid: [-1.0, 1.0]. Default: 0.5.
nls_config.turn_detection.silence_duration_msintTidakDurasi hening minimum setelah ucapan, dalam milidetik, sebelum respons model dipicu. Parameter ini hanya berlaku untuk server_vad dan tidak berpengaruh pada smart_turn. Nilai yang lebih rendah mengurangi latensi tetapi dapat terpicu pada jeda singkat. Rentang yang valid: [200, 6000]. Default: 800. Direkomendasikan untuk percakapan: 400 hingga 800.
nls_config.turn_detection.voiceprint_audio_urlsstringTidakString yang berisi array URL audio prarekaman yang dapat diakses publik untuk pembicara target. Parameter ini hanya berlaku untuk smart_turn. Dalam percakapan dupleks, ini membantu model fokus pada pembicara target dan mengabaikan pembicara lain serta kebisingan latar belakang. Mendukung hingga lima URL. Audio harus berupa PCM atau WAV 16 kHz.

API Utama

NeoNui

nui_initialize

Menginisialisasi instance SDK percakapan suara. SDK ini adalah singleton. Jangan menginisialisasinya lagi sebelum Anda memanggil nui_release. Signature metode
-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;
Deskripsi parameter

Parameter

Tipe

Deskripsi

parameters

char*

String JSON yang berisi parameter autentikasi, koneksi, dan debugging. Lihat Parameter koneksi dan kontrol.

level

NuiSdkLogLevel

Tingkat cetak untuk log SDK itu sendiri.

save_log

BOOL

Apakah akan menyimpan log secara lokal. Jika diatur ke YES, tentukan jalur dengan debug_path di Connection and control parameters, dan secara opsional atur ukuran file dengan max_log_file_size.

nui_set_params

Mengatur Voice conversation parameters dalam format JSON. Panggil metode ini sebelum nui_dialog_start. Signature metode
-(NuiResultCode) nui_set_params:(const char *)params;
Deskripsi parameter

Parameter

Tipe

Deskripsi

params

char*

Parameter percakapan suara.

nui_dialog_start

Memulai percakapan. Signature metode
-(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;
Parameter
ParameterTipeDeskripsi
vad_modeNuiVadModeMode VAD. Tetap pada MODE_P2T.
dialog_paramschar*Jika apikey dalam parameter koneksi dan kontrol adalah API key sementara, perbarui di sini setelah kedaluwarsa.
Format JSON:
{
  "apikey": "st-****"
}

nui_dialog_cancel

Mengakhiri percakapan atau segera membatalkan interaksi saat ini. Signature metode
-(NuiResultCode) nui_dialog_cancel:(BOOL)force;
Deskripsi parameter

Parameter

Tipe

Deskripsi

force

BOOL

Apakah akan mengakhiri secara paksa dan membuang hasil akhir.

  • YES: Akhiri tugas segera tanpa menunggu server mengembalikan hasil percakapan akhir.

  • NO: Akhiri tugas, tetapi tunggu hasil lengkap dikembalikan.

nui_dialog_action

Mengirimkan perintah tindakan percakapan selama interaksi untuk memperbarui perilaku runtime seperti konteks percakapan. Signature metode
- (NuiResultCode) nui_dialog_action:(const char *)params;
Parameter
ParameterTipeDeskripsi
paramschar*String JSON yang digunakan untuk memperbarui perilaku runtime seperti konteks percakapan.
params.typeStringAtur ke "action".
params.commandStringPerintah runtime. Nilai yang valid:
  • function_call: memperbarui permintaan function call.
  • play_start: ketika AEC pada perangkat digunakan, memberi tahu SDK bahwa pemutaran audio telah dimulai.
  • play_over: ketika AEC pada perangkat digunakan, memberi tahu SDK bahwa pemutaran audio telah berakhir.
params.contextStringPembaruan permintaan function call. Digunakan ketika command adalah "function_call".
params.context.typeStringTipe event. Parameter ini wajib diisi jika command adalah "function_call". conversation.item.create menyisipkan item percakapan untuk konteks historis, teks tambahan, atau hasil alat. Setelah mengirim conversation.item.create, gunakan response.create untuk memicu inferensi lain.
params.context.itemobjectWajib ketika params.context.type adalah conversation.item.create. Item percakapan yang akan dibuat.
params.context.responseobjectOpsional jika params.context.type adalah response.create. Menimpa default sesi untuk inferensi ini. Jika diabaikan, konfigurasi sesi saat ini akan digunakan.
Parameter context.item:
ParameterTipeDeskripsi
idStringID item percakapan unik opsional. Jika diabaikan, server akan membuatnya. Error akan dikembalikan jika ID yang ditentukan sudah ada.
typeStringTipe item wajib. Nilai yang valid:
  • message: pesan reguler.
  • function_call: permintaan pemanggilan fungsi. Tipe ini biasanya dibuat oleh server. Klien juga dapat menggunakannya untuk menambahkan konteks historis.
  • function_call_output: hasil eksekusi alat. Setelah menerima function_call, klien menjalankan alat dan menggunakan tipe ini untuk menulis kembali hasilnya.
roleStringWajib untuk message. Nilai yang valid: system, user, dan assistant.
contentarrayWajib untuk message. Setiap item berisi type dan bidang data terkait. system mendukung input_text dengan text; user mendukung input_text dengan text dan input_audio dengan audio yang dienkode Base64; assistant mendukung output_text dengan text.
call_idStringWajib untuk function_call dan function_call_output. ID unik yang mengaitkan permintaan pemanggilan fungsi dengan hasilnya.
nameStringWajib untuk function_call. Nama fungsi yang akan dipanggil.
argumentsStringWajib untuk function_call. Argumen fungsi sebagai string JSON.
outputStringWajib untuk function_call_output. Hasil eksekusi tool sebagai string JSON.
Parameter context.response:
ParameterTipeDeskripsi
modalitiesarrayModalitas output. ["text"] hanya mengembalikan teks. ["audio", "text"] (default) mengembalikan audio dan teks.
voicestringMenimpa suara TTS untuk inferensi ini.
Contoh:
{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"Hangzhou\",\"condition\":\"sunny\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": ["text", "audio"]
    },
    "type": "response.create"
  }
}

nui_update_audio_data

Saat audio_update_manually diatur ke "true", data rekaman tidak lagi dipasok melalui onNuiNeedAudioData. Gunakan metode ini untuk mendorongnya secara aktif sebagai gantinya. Signature metode
-(NuiResultCode) nui_update_audio_data:(const char *)data
                                    Len:(int)length
                              FirstPack:(BOOL)first_pack;
Deskripsi parameter

Parameter

Tipe

Deskripsi

data

const char *

Data audio yang akan di-push.

length

int

Panjang data audio, dalam byte.

first_pack

BOOL

Anda tidak perlu menggunakan parameter ini.

nui_push_reference_data

Saat audio_update_manually diatur ke "true" dan acoustic echo cancellation (AEC) pada perangkat diaktifkan, gunakan metode ini untuk mendorong audio yang diputar oleh pemutar sebagai sinyal referensi. Signature metode
-(NuiResultCode) nui_push_reference_data:(const char *)data
                                     Len:(int)length
                               FirstPack:(BOOL)first_pack;
Deskripsi parameter

Parameter

Tipe

Deskripsi

data

const char *

Data audio yang akan di-push.

length

int

Panjang data audio, dalam byte.

first_pack

BOOL

Anda tidak perlu menggunakan parameter ini.

nui_release

Melepaskan semua sumber daya internal SDK dan menghentikan paksa semua tugas yang berjalan. Setelah Anda memanggil metode ini, instance SDK menjadi tidak tersedia. Untuk menggunakannya lagi, Anda harus memanggil nui_initialize untuk menginisialisasinya kembali. Signature metode
-(NuiResultCode) nui_release;

nui_get_version

Mendapatkan versi SDK saat ini. Metode ini mengembalikan nilai hanya setelah nui_initialize dipanggil. Signature metode
-(const char*) nui_get_version;
Nilai kembalian Versi SDK saat ini.

nui_get_all_response

Mendapatkan informasi lengkap untuk callback event saat ini. Signature metode
-(const char*) nui_get_all_response;
Nilai kembalian Informasi event lengkap sebagai string JSON.

NeoNuiSdkDelegate: listener callback

onNuiEventCallback: mendengarkan informasi event

Signature metode
-(void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                    dialog:(long)dialog
                 kwsResult:(const char *)wuw
                 asrResult:(const char *)asr_result
                  ifFinish:(BOOL)finish
                   retCode:(int)code;
Deskripsi parameter

Parameter

Tipe

Deskripsi

nuiEvent

NuiCallbackEvent

Event callback.

dialog

long

ID Sesi. Anda tidak perlu menggunakan parameter ini.

wuw

char*

Voice wake-up. Anda tidak perlu menggunakan parameter ini.

asr_result

char*

Hasil pengenalan ucapan.

finish

BOOL

Apakah putaran pengenalan saat ini telah selesai.

code

int

Hanya valid saat event EVENT_ASR_ERROR terjadi.

onNuiAudioStateChanged: mendengarkan status audio

SDK menggunakan callback ini untuk memberi tahu Anda kapan harus memulai atau menghentikan perekaman. Signature metode
-(void) onNuiAudioStateChanged:(NuiAudioState)state;
Status NuiAudioState

Parameter

Deskripsi

STATE_OPEN

Interaksi telah dimulai. Anda dapat membuka perangkat perekaman dan memulai perekaman.

STATE_PAUSE

Interaksi telah berhenti. Anda dapat menghentikan perekaman.

STATE_CLOSE

Instans SDK telah dilepaskan. Anda dapat menutup perangkat perekaman sepenuhnya.

onNuiNeedAudioData: memasok data audio

Setelah percakapan dimulai, callback ini dipicu secara terus-menerus. Sediakan data audio di callback ini. Anda tidak perlu menggunakan callback ini saat audio_update_manually diatur ke "true". Signature metode
-(int) onNuiNeedAudioData:(char *)audioData length:(int)len;
Deskripsi parameter

Parameter

Tipe

Deskripsi

audioData

char *

Data audio yang akan diberikan.

len

int

Ukuran data audio yang diberikan, dalam byte.

onNuiAssistEventCallback: menerima data dan informasi tambahan

Menerima event tambahan dan data terkait dari SDK. Signature metode
-(void) onNuiAssistEventCallback:(NuiCallbackEvent)nuiEvent
                            info:(char*)info
                         infoLen:(int)info_len
                          buffer:(char*)buffer
                             len:(int)len;
Deskripsi parameter

Parameter

Tipe

Deskripsi

nuiEvent

NuiCallbackEvent

Event callback.

info

char *

Anda tidak perlu menggunakan parameter ini.

info_len

int

Anda tidak perlu menggunakan parameter ini.

buffer

char *

Data tambahan, seperti audio TTS yang dikembalikan oleh model.

len

int

Panjang data tambahan, dalam byte.

onNuiLogTrackCallback: mendengarkan log pelacakan

Callback ini menerima log internal terperinci SDK untuk membantu Anda menemukan dan men-debug masalah.
-(void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
                   logMessage:(const char *)log;

NuiCallbackEvent: tipe event

EventDeskripsi
EVENT_TRANSCRIBER_STARTEDTugas berhasil dimulai.
EVENT_VAD_STARTDipicu segera setelah tugas dimulai. Ini tidak berarti bahwa awal ucapan telah terdeteksi.
EVENT_VAD_ENDAkhir ucapan terdeteksi.
EVENT_ASR_PARTIAL_RESULTHasil pengenalan ucapan sementara.
EVENT_ASR_ERRORTerjadi kesalahan selama percakapan suara.
EVENT_MIC_ERRORDipicu ketika tidak ada data audio yang diterima selama dua detik berturut-turut.
EVENT_SENTENCE_ENDAkhir kalimat terdeteksi dan hasil pengenalan lengkap dikembalikan.
EVENT_TRANSCRIBER_COMPLETEPercakapan suara berakhir.
EVENT_AUDIO_TRANSCRIPTIONEvent transkripsi teks inkremental untuk output audio. Segmen transkripsi dikembalikan dalam mode streaming.
EVENT_AUDIO_TRANSCRIPTION_COMPLETEDTranskrip untuk output audio telah selesai.
EVENT_OTHER_RESULTInformasi event lainnya, seperti hasil Function Calling.
EVENT_ASR_TTS_STARTModel mulai mengembalikan audio TTS.
EVENT_ASR_TTS_DATAAudio TTS yang dikembalikan oleh model.
EVENT_ASR_TTS_COMPLETEModel selesai mengembalikan audio TTS.
EVENT_AEC_DATAData audio yang diproses oleh AEC.
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Realtime API
Penyematan Teks
TokenPlan
Model production