Referensi peristiwa klien untuk API Qwen-Audio-Realtime.
Panduan pengguna: Percakapan suara realtime (Qwen-Audio-Realtime). Untuk urutan interaksi peristiwa, lihat Akses WebSocket.
Untuk penggunaan SDK WebSocket, lihat SDK Android, SDK iOS, dan SDK HarmonyOS. Untuk memilih model dan protokol, lihat Gambaran umum.
Deskripsi: Setelah koneksi terbentuk, kirim event ini untuk memperbarui konfigurasi sesi default. Sertakan hanya bidang yang ingin diubah; bidang yang dihilangkan mempertahankan nilai saat ini. Jika terdapat parameter tidak valid, server mengembalikan error. Jika semua parameter valid, server menerapkan perubahan dan mengembalikan konfigurasi lengkap.
Jenis event. Nilai tetap: Konfigurasi sesi.
Modalitas output untuk model. Nilai yang valid:Nama suara TTS. Default adalah Mengontrol kecepatan bicara output audio model. Rentang: Menentukan apakah peningkatan emosi suara diaktifkan. Saat diaktifkan, suara respons menunjukkan variasi emosi yang lebih jelas. Default: Instruksi sistem yang menentukan peran model, gaya respons, dan preferensi perilaku. Berlaku untuk seluruh sesi.Format audio input. Saat ini hanya Format audio output. Saat ini hanya Konfigurasi transkripsi audio input.
Bahasa sumber audio input. Berlaku untuk Konfigurasi hotword instan untuk transkripsi audio input. Berlaku untuk
Objek yang memetakan hotword ke bobot bilangan bulat. Hotword biasa memiliki bobot dari 1 hingga 5. Semakin tinggi bobotnya, semakin besar kemungkinan transkripsi menggunakan kata tersebut. Bobot 50 menandai super hotword. Anda dapat menyertakan hingga 50 super hotword dan hingga 2.000 hotword secara total per pembaruan.Mengirim objek Konfigurasi audio output. Berlaku untuk
Bahasa target audio output.Parameter ini berlaku untuk text-to-speech (TTS). Model berusaha semaksimal mungkin menghasilkan ucapan dalam bahasa target, tetapi hal ini tidak dijamin, dan bahasa teks respons tidak berubah. Untuk menghasilkan teks dalam bahasa target, nyatakan persyaratan tersebut secara eksplisit dalam prompt, misalnya dengan menentukan bahasa balasan di Jumlah maksimum giliran percakapan (pasangan pertanyaan-jawaban) yang disertakan dalam satu permintaan. Nilai yang valid: 1 hingga 50. Default: 20.Berlaku untuk model qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash.Menentukan apakah penelusuran web diaktifkan. Default: Konfigurasi penelusuran web. Parameter ini hanya berlaku jika
Menentukan apakah sumber hasil penelusuran dikembalikan. Atur parameter ini ke Definisi tool untuk Function Calling. Setelah dikonfigurasi, model memutuskan apakah akan memanggil tool berdasarkan input pengguna.
Nilai tetap:
Nama fungsi tool.Deskripsi fungsi tool. Model menggunakan ini untuk menentukan apakah akan memanggil tool.Deskripsi parameter input fungsi tool. Model menggunakan ini untuk mengekstrak parameter yang diperlukan. Abaikan bidang ini jika fungsi tidak memiliki parameter.
Nilai tetap: Menjelaskan nama, tipe data, dan deskripsi setiap parameter.Menentukan parameter mana yang wajib diisi.Bidang deteksi giliran yang dijelaskan di bawah ini berlaku untuk
Jenis VAD. Nilai yang valid:Sensitivitas VAD. Berlaku untuk Durasi diam minimum (dalam milidetik) setelah ucapan berakhir sebelum memicu respons model. Hanya berlaku dalam mode server_vad (diabaikan dalam mode smart_turn / smart_turn_v2). Nilai yang lebih rendah menghasilkan respons lebih cepat tetapi dapat menyebabkan pemicuan salah selama jeda singkat.Rentang: [200, 6000]. Default: 800. Rentang yang direkomendasikan untuk percakapan: 400-800.Hanya berlaku dalam mode smart_turn / smart_turn_v2. Daftar URL yang dapat diakses publik yang mengarah ke sampel audio rekaman dari pengguna target, digunakan untuk peningkatan speaker. Setelah didaftarkan, model mengunci speaker target selama percakapan duplex, secara efektif mengabaikan suara lain dan kebisingan latar. Maksimal 5 URL. Persyaratan format audio: PCM atau WAV 16 kHz.
Deskripsi: Untuk akses WebSocket, menambahkan data audio ke buffer input. Kirim data secara terus-menerus dengan interval pendek, misalnya satu frame setiap 20~40 ms. Server tidak mengirim konfirmasi untuk event ini.
Jenis event. Nilai tetap: Data audio yang dienkode Base64.
Deskripsi: Hanya untuk mode push-to-talk. Mengomit buffer audio sebagai pesan pengguna. Ini tidak secara otomatis memicu inferensi. Kirim Jenis event. Nilai tetap:
Deskripsi: Untuk akses WebSocket, event ini hanya berlaku dalam mode push-to-talk. Menghapus audio yang belum dikomit dari buffer. Event ini diabaikan dalam mode server_vad / smart_turn / smart_turn_v2. Server merespons dengan event Jenis event. Nilai tetap:
Deskripsi: Menyisipkan item percakapan ke dalam konteks percakapan. Gunakan event ini untuk menyuntikkan konteks historis atau menambahkan konten teks, atau untuk mengembalikan hasil Function Calling.
Jenis event. Nilai tetap: Menentukan item percakapan tempat item baru akan disisipkan setelahnya. Jika tidak disediakan, item ditambahkan di akhir percakapan.Item percakapan yang akan dibuat.
Identifier unik untuk item percakapan. Jika tidak disediakan, server menghasilkannya secara otomatis. Error dikembalikan jika ID yang ditentukan sudah ada dalam percakapan.Jenis item percakapan. Nilai yang valid:Peran pesan. Nilai yang valid: Daftar elemen konten pesan. Setiap elemen berisi bidang
Identifier unik untuk pemanggilan fungsi, digunakan untuk menghubungkan permintaan dan hasil.Nama fungsi yang akan dipanggil.Parameter pemanggilan fungsi dalam format string JSON.Hasil eksekusi tool dalam format string JSON.
Deskripsi: Mengambil item percakapan yang disimpan di server. Konten bertipe audio dalam respons hanya berisi transkrip (Jenis event. Nilai tetap: ID item percakapan yang akan diambil. Server mengembalikan hasilnya dalam event
Deskripsi: Menghapus item percakapan dari konteks percakapan. Server mengonfirmasi penghapusan dengan event Jenis event. Nilai tetap: ID item percakapan yang akan dihapus.
Deskripsi: Memicu inferensi model. Perilaku bervariasi berdasarkan mode:
Jenis event. Nilai tetap: Mengganti default sesi untuk putaran inferensi saat ini. Jika tidak disediakan, konfigurasi sesi saat ini yang digunakan.
Mengganti modalitas output untuk putaran ini. Nilai yang valid sama dengan Mengganti suara TTS untuk putaran ini.
Deskripsi: Membatalkan inferensi saat ini. Teks yang telah dihasilkan sejauh ini disimpan ke daftar item. Server kemudian mengembalikan event Jenis event. Nilai tetap:
Halaman ini adalah referensi peristiwa untuk Qwen-Audio-Realtime. Definisi peristiwa didasarkan pada akses WebSocket. AOQ dan WebRTC menggunakan saluran data masing-masing untuk mengirim dan menerima peristiwa model, serta track media untuk mengirimkan media. Baca terlebih dahulu Akses WebSocket, Akses WebRTC, atau Akses AOQ.
session.update
Deskripsi: Setelah koneksi terbentuk, kirim event ini untuk memperbarui konfigurasi sesi default. Sertakan hanya bidang yang ingin diubah; bidang yang dihilangkan mempertahankan nilai saat ini. Jika terdapat parameter tidak valid, server mengembalikan error. Jika semua parameter valid, server menerapkan perubahan dan mengembalikan konfigurasi lengkap.
turn_detection hanya dapat dimodifikasi sebelum audio pertama dikirim (status IDLE).typestring(wajib)session.update.sessionobject(opsional)Properti
Properti
modalitiesarray(opsional)-
["text"]Hanya teks. -
["audio", "text"](default) Teks dan audio.
voicestring(opsional)longanqian_v3.1 untuk 3.1 Plus/Flash dan longanqian untuk 3.0 Plus/Flash. Suara sistem dan suara kloning didukung. Hanya dapat diatur pada session.update pertama; diabaikan pada pemanggilan berikutnya.- Suara sistem untuk 3.1 Plus/Flash: Mendukung
longanqian_v3.1serta gabungan daftar suara untuk 3.1 TTS Plus dan Flash. Untuk rentang lengkap, lihat Konfigurasi suara. - Suara sistem untuk 3.0 Plus/Flash: Nilai yang tersedia:
longanqian,longanlingxin,longanlingxi,longanxiaoxin,longanlufeng. - Suara kloning: Buat suara melalui API kloning suara, lalu atur parameter ini ke
voice_idyang dikembalikan. Untuk detailnya, lihat Konfigurasi suara.
qwen-audio-3.1-realtime-plus atau qwen-audio-3.1-realtime-flash, atur suara pada session.update pertama, misalnya:speech_ratefloat(opsional)[0.5, 2.0]. Default: 1.0. Nilai yang lebih rendah memperlambat ucapan; nilai yang lebih tinggi mempercepatnya. Didukung oleh qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash.enable_speech_emotionboolean(opsional)true. Nilai yang valid: true dan false.instructionsstring(opsional)input_audio_formatstring(opsional)pcm (16 kHz, 16-bit, mono) yang didukung dan merupakan default. Hanya dapat dimodifikasi sebelum audio pertama dikirim (status IDLE).output_audio_formatstring(opsional)pcm (24 kHz, 16-bit, mono) yang didukung dan merupakan default.input_audio_transcriptionobject(opsional)Properti
Properti
languagestring(opsional)qwen-audio-3.1-realtime-plus dan qwen-audio-3.1-realtime-flash. Hotword instan juga tetap berfungsi jika bidang ini dihilangkan.Nilai yang valid:zh: bahasa Tionghoaen: bahasa Inggrisja: bahasa Jepangko: bahasa Koreavi: bahasa Vietnamth: bahasa Thaiid: bahasa Indonesiaar: bahasa Arabfr: bahasa Prancisde: bahasa Jermanes: bahasa Spanyolpt: bahasa Portugisru: bahasa Rusiait: bahasa Italia
corpusobject(opsional)qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, qwen-audio-3.1-realtime-plus, dan qwen-audio-3.1-realtime-flash.Properti
Properti
vocabularyobjectvocabulary lain dalam sesi yang sama menggantikan seluruh daftar sebelumnya. Kirim objek kosong {} untuk menghapus hotword.output_audioobject(opsional)qwen-audio-3.1-realtime-plus dan qwen-audio-3.1-realtime-flash.Properti
Properti
languagestring(opsional)instructions.Nilai yang valid:zh: bahasa Tionghoaen: bahasa Inggrisfr: bahasa Prancisde: bahasa Jermanja: bahasa Jepangko: bahasa Korearu: bahasa Rusiapt: bahasa Portugisth: bahasa Thaiid: bahasa Indonesiavi: bahasa Vietnames: bahasa Spanyolit: bahasa Italiaar: bahasa Arab
max_history_turnsinteger(opsional)enable_searchboolean(opsional)false. Saat diaktifkan, model memutuskan apakah akan menelusuri web berdasarkan kueri secara realtime.Anda dapat mengatur enable_search ke true dan mengonfigurasi tool Function Calling melalui tools dalam sesi yang sama.search_optionsobject(opsional)enable_search diatur ke true.Properti
Properti
enable_sourceboolean(opsional)true untuk mengembalikan sumber.toolsarray(opsional)Properti
Properti
typestring(wajib)function.functionobjectProperti
Properti
namestring(wajib)descriptionstring(opsional)parametersobject(opsional)Properti
Properti
typestring(wajib)object.propertiesobject(opsional)requiredarray(opsional)turn_detectionobject|null(opsional)qwen-audio-3.1-realtime-plus, qwen-audio-3.1-realtime-flash, qwen-audio-3.0-realtime-plus, dan qwen-audio-3.0-realtime-flash.Konfigurasi deteksi giliran. Untuk beralih ke mode push-to-talk, atur bidang ini ke null. Dalam mode push-to-talk, audio harus dikomit secara manual dan inferensi dipicu secara manual. Jika bidang ini tidak disediakan, VAD diaktifkan dengan parameter default-nya.Properti
Properti
typestring(opsional)server_vad(default): Mendeteksi awal dan akhir ucapan berdasarkan fitur akustik dan secara otomatis memicu inferensi.smart_turn: Mode deteksi giliran cerdas yang menggabungkan persepsi akustik dan pemahaman semantik untuk menentukan batas giliran. Suara pengisi seperti "um" atau "uh" tidak memicu giliran baru atau mengganggu pemutaran model.smart_turn_v2(direkomendasikan): Dibangun di atassmart_turnuntuk lebih memahami konteks percakapan dan maksud interaksi dalam lingkungan multi-pembicara. Mengurangi respons atau interupsi yang tidak diinginkan akibat orang di sekitar atau interjeksi yang tidak relevan.
thresholdfloat(opsional)server_vad, smart_turn, dan smart_turn_v2. Nilai yang lebih rendah meningkatkan sensitivitas VAD, sehingga suara pelan (termasuk kebisingan latar) lebih mudah terdeteksi sebagai ucapan. Nilai yang lebih tinggi menurunkan sensitivitas, sehingga diperlukan ucapan yang lebih jelas dan keras untuk memicu deteksi.Rentang: [-1.0, 1.0]. Default: 0.5.silence_duration_msinteger(opsional)voiceprint_audio_urlsarray(opsional)- Konfigurasi dasar
- Konfigurasi bahasa
- Hotword instan
- Function Calling
- Registrasi voiceprint
Contoh di bawah berlaku untuk
qwen-audio-3.1-realtime-plus dan qwen-audio-3.1-realtime-flash dan secara eksplisit memilih suara sistem longanqian_v3.1.input_audio_buffer.append
Deskripsi: Untuk akses WebSocket, menambahkan data audio ke buffer input. Kirim data secara terus-menerus dengan interval pendek, misalnya satu frame setiap 20~40 ms. Server tidak mengirim konfirmasi untuk event ini.
typestring(wajib)input_audio_buffer.append.audiostring(wajib)input_audio_buffer.commit
Deskripsi: Hanya untuk mode push-to-talk. Mengomit buffer audio sebagai pesan pengguna. Ini tidak secara otomatis memicu inferensi. Kirim response.create untuk memicu inferensi secara manual.
Event ini diabaikan dalam mode server_vad, smart_turn, dan smart_turn_v2.
typestring(wajib)input_audio_buffer.commit.input_audio_buffer.clear
Deskripsi: Untuk akses WebSocket, event ini hanya berlaku dalam mode push-to-talk. Menghapus audio yang belum dikomit dari buffer. Event ini diabaikan dalam mode server_vad / smart_turn / smart_turn_v2. Server merespons dengan event input_audio_buffer.cleared.
typestring(wajib)input_audio_buffer.clear.conversation.item.create
Deskripsi: Menyisipkan item percakapan ke dalam konteks percakapan. Gunakan event ini untuk menyuntikkan konteks historis atau menambahkan konten teks, atau untuk mengembalikan hasil Function Calling.
Jika
item.id sudah ada dalam percakapan, error dikembalikan dan item tidak dibuat.typestring(wajib)conversation.item.create.previous_item_idstring(opsional)itemobject(wajib)Properti
Properti
idstring(opsional)typestring(wajib)message: Pesan percakapan biasa.function_call: Permintaan pemanggilan fungsi. Biasanya dihasilkan oleh server, tetapi klien juga dapat menggunakannya untuk menyuntikkan konteks historis.function_call_output: Hasil eksekusi tool. Setelah menerimafunction_call, klien mengeksekusi tool dan mengembalikan hasilnya menggunakan jenis ini.
rolestring(wajib untuk jenis message)system, user, assistant.contentarray(wajib untuk jenis message)type dan bidang data terkait.Jenis konten yang didukung berdasarkan peran
Jenis konten yang didukung berdasarkan peran
system
input_text: Pesan sistem. Bidang wajib: text.userinput_text: Input teks pengguna. Bidang wajib:text.input_audio: Input audio pengguna. Bidang wajib:audio(dienkode Base64).
output_text: Output teks asisten. Bidang wajib: text.call_idstring(wajib untuk jenis function_call / function_call_output)namestring(wajib untuk jenis function_call)argumentsstring(wajib untuk jenis function_call)outputstring(wajib untuk jenis function_call_output)- Pesan teks pengguna
- Hasil Function Calling
Menyuntikkan pesan teks pengguna:
conversation.item.retrieve
Deskripsi: Mengambil item percakapan yang disimpan di server. Konten bertipe audio dalam respons hanya berisi transkrip (transcript), bukan data audio aslinya.
typestring(wajib)conversation.item.retrieve.item_idstring(wajib)conversation.item.retrieved.conversation.item.delete
Deskripsi: Menghapus item percakapan dari konteks percakapan. Server mengonfirmasi penghapusan dengan event conversation.item.deleted.
typestring(wajib)conversation.item.delete.item_idstring(wajib)response.create
Deskripsi: Memicu inferensi model. Perilaku bervariasi berdasarkan mode:
- Mode push-to-talk: Harus dipanggil secara manual. Komit buffer audio terlebih dahulu dengan
input_audio_buffer.commit, atau kembalikan hasilfunction_call_outputsebelum memicu. Tidak dapat dipanggil saat respons sedang dihasilkan. - Mode server_vad: Biasanya dipicu secara otomatis oleh server. Klien juga dapat memanggilnya secara manual saat tidak ada respons yang sedang dihasilkan. Tidak dapat dipanggil saat respons sedang dihasilkan.
- Mode smart_turn / smart_turn_v2: Dapat dipanggil saat menunggu giliran pengguna berikutnya. Tidak dapat dipanggil selama giliran aktif (antara
input_audio_buffer.speech_starteddanresponse.done).
response mengganti default sesi untuk putaran inferensi saat ini. Dalam skenario Function Calling, setelah klien mengembalikan function_call_output, event ini memicu putaran inferensi kedua.
Dalam mode server_vad, smart_turn, dan smart_turn_v2, inferensi yang dipicu secara manual tetap dapat diinterupsi oleh ucapan baru.
typestring(wajib)response.create.responseobject(opsional)Properti
Properti
modalitiesarray(opsional)modalities pada session.update.voicestring(opsional)response.cancel
Deskripsi: Membatalkan inferensi saat ini. Teks yang telah dihasilkan sejauh ini disimpan ke daftar item. Server kemudian mengembalikan event response.done dengan status=cancelled.
Error dikembalikan jika tidak ada inferensi yang sedang berlangsung.
typestring(wajib)response.cancel.