Skip to main content

Event klien Qwen-Audio-Realtime

Referensi peristiwa klien untuk API Qwen-Audio-Realtime.

Panduan pengguna: Percakapan suara realtime (Qwen-Audio-Realtime). Untuk urutan interaksi peristiwa, lihat Akses WebSocket.
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.
Untuk penggunaan SDK WebSocket, lihat SDK Android, SDK iOS, dan SDK HarmonyOS. Untuk memilih model dan protokol, lihat Gambaran umum.

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)
Jenis event. Nilai tetap: session.update.
sessionobject(opsional)
Konfigurasi sesi.
modalitiesarray(opsional)
Modalitas output untuk model. Nilai yang valid:
  • ["text"] Hanya teks.
  • ["audio", "text"] (default) Teks dan audio.
voicestring(opsional)
Nama suara TTS. Default adalah 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.1 serta 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_id yang dikembalikan. Untuk detailnya, lihat Konfigurasi suara.
Setelah terhubung ke qwen-audio-3.1-realtime-plus atau qwen-audio-3.1-realtime-flash, atur suara pada session.update pertama, misalnya:
{
    "type": "session.update",
    "session": {
        "voice": "longanqian_v3.1"
    }
}
speech_ratefloat(opsional)
Mengontrol kecepatan bicara output audio model. Rentang: [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)
Menentukan apakah peningkatan emosi suara diaktifkan. Saat diaktifkan, suara respons menunjukkan variasi emosi yang lebih jelas. Default: true. Nilai yang valid: true dan false.
instructionsstring(opsional)
Instruksi sistem yang menentukan peran model, gaya respons, dan preferensi perilaku. Berlaku untuk seluruh sesi.
input_audio_formatstring(opsional)
Format audio input. Saat ini hanya pcm (16 kHz, 16-bit, mono) yang didukung dan merupakan default. Hanya dapat dimodifikasi sebelum audio pertama dikirim (status IDLE).
output_audio_formatstring(opsional)
Format audio output. Saat ini hanya pcm (24 kHz, 16-bit, mono) yang didukung dan merupakan default.
input_audio_transcriptionobject(opsional)
Konfigurasi transkripsi audio input.
languagestring(opsional)
Bahasa sumber audio input. Berlaku untuk 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 Tionghoa
  • en: bahasa Inggris
  • ja: bahasa Jepang
  • ko: bahasa Korea
  • vi: bahasa Vietnam
  • th: bahasa Thai
  • id: bahasa Indonesia
  • ar: bahasa Arab
  • fr: bahasa Prancis
  • de: bahasa Jerman
  • es: bahasa Spanyol
  • pt: bahasa Portugis
  • ru: bahasa Rusia
  • it: bahasa Italia
corpusobject(opsional)
Konfigurasi hotword instan untuk transkripsi audio input. Berlaku untuk 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.
vocabularyobject
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 vocabulary lain dalam sesi yang sama menggantikan seluruh daftar sebelumnya. Kirim objek kosong {} untuk menghapus hotword.
output_audioobject(opsional)
Konfigurasi audio output. Berlaku untuk qwen-audio-3.1-realtime-plus dan qwen-audio-3.1-realtime-flash.
languagestring(opsional)
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 instructions.Nilai yang valid:
  • zh: bahasa Tionghoa
  • en: bahasa Inggris
  • fr: bahasa Prancis
  • de: bahasa Jerman
  • ja: bahasa Jepang
  • ko: bahasa Korea
  • ru: bahasa Rusia
  • pt: bahasa Portugis
  • th: bahasa Thai
  • id: bahasa Indonesia
  • vi: bahasa Vietnam
  • es: bahasa Spanyol
  • it: bahasa Italia
  • ar: bahasa Arab
max_history_turnsinteger(opsional)
Jumlah maksimum giliran percakapan (pasangan pertanyaan-jawaban) yang disertakan dalam satu permintaan. Nilai yang valid: 1 hingga 50. Default: 20.
enable_searchboolean(opsional)
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: 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)
Konfigurasi penelusuran web. Parameter ini hanya berlaku jika enable_search diatur ke true.
enable_sourceboolean(opsional)
Menentukan apakah sumber hasil penelusuran dikembalikan. Atur parameter ini ke true untuk mengembalikan sumber.
toolsarray(opsional)
Definisi tool untuk Function Calling. Setelah dikonfigurasi, model memutuskan apakah akan memanggil tool berdasarkan input pengguna.
typestring(wajib)
Nilai tetap: function.
functionobject
namestring(wajib)
Nama fungsi tool.
descriptionstring(opsional)
Deskripsi fungsi tool. Model menggunakan ini untuk menentukan apakah akan memanggil tool.
parametersobject(opsional)
Deskripsi parameter input fungsi tool. Model menggunakan ini untuk mengekstrak parameter yang diperlukan. Abaikan bidang ini jika fungsi tidak memiliki parameter.
typestring(wajib)
Nilai tetap: object.
propertiesobject(opsional)
Menjelaskan nama, tipe data, dan deskripsi setiap parameter.
requiredarray(opsional)
Menentukan parameter mana yang wajib diisi.
turn_detectionobject|null(opsional)
Bidang deteksi giliran yang dijelaskan di bawah ini berlaku untuk 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.
typestring(opsional)
Jenis VAD. Nilai yang valid:
  • 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 atas smart_turn untuk 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)
Sensitivitas VAD. Berlaku untuk 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)
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.
voiceprint_audio_urlsarray(opsional)
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.
Parameter ini hanya dapat dikonfigurasi pada event session.update pertama. Parameter ini diabaikan pada event session.update berikutnya.
  • 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.
{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian_v3.1",
        "speech_rate": 1.2,
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}

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)
Jenis event. Nilai tetap: input_audio_buffer.append.
audiostring(wajib)
Data audio yang dienkode Base64.
{
    "type": "input_audio_buffer.append",
    "audio": "<Base64-encoded audio data>"
}

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)
Jenis event. Nilai tetap: input_audio_buffer.commit.
{
    "type": "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)
Jenis event. Nilai tetap: input_audio_buffer.clear.
{
    "type": "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)
Jenis event. Nilai tetap: conversation.item.create.
previous_item_idstring(opsional)
Menentukan item percakapan tempat item baru akan disisipkan setelahnya. Jika tidak disediakan, item ditambahkan di akhir percakapan.
itemobject(wajib)
Item percakapan yang akan dibuat.
idstring(opsional)
Identifier unik untuk item percakapan. Jika tidak disediakan, server menghasilkannya secara otomatis. Error dikembalikan jika ID yang ditentukan sudah ada dalam percakapan.
typestring(wajib)
Jenis item percakapan. Nilai yang valid:
  • 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 menerima function_call, klien mengeksekusi tool dan mengembalikan hasilnya menggunakan jenis ini.
rolestring(wajib untuk jenis message)
Peran pesan. Nilai yang valid: system, user, assistant.
contentarray(wajib untuk jenis message)
Daftar elemen konten pesan. Setiap elemen berisi bidang type dan bidang data terkait.
systeminput_text: Pesan sistem. Bidang wajib: text.user
  • input_text: Input teks pengguna. Bidang wajib: text.
  • input_audio: Input audio pengguna. Bidang wajib: audio (dienkode Base64).
assistantoutput_text: Output teks asisten. Bidang wajib: text.
call_idstring(wajib untuk jenis function_call / function_call_output)
Identifier unik untuk pemanggilan fungsi, digunakan untuk menghubungkan permintaan dan hasil.
namestring(wajib untuk jenis function_call)
Nama fungsi yang akan dipanggil.
argumentsstring(wajib untuk jenis function_call)
Parameter pemanggilan fungsi dalam format string JSON.
outputstring(wajib untuk jenis function_call_output)
Hasil eksekusi tool dalam format string JSON.
  • Pesan teks pengguna
  • Hasil Function Calling
Menyuntikkan pesan teks pengguna:
{
    "type": "conversation.item.create",
    "previous_item_id": "item_xxx",
    "item": {
        "id": "my_item_001",
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "Please summarize our last conversation"
            }
        ]
    }
}

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)
Jenis event. Nilai tetap: conversation.item.retrieve.
item_idstring(wajib)
ID item percakapan yang akan diambil. Server mengembalikan hasilnya dalam event conversation.item.retrieved.
{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}

conversation.item.delete

Deskripsi: Menghapus item percakapan dari konteks percakapan. Server mengonfirmasi penghapusan dengan event conversation.item.deleted.
typestring(wajib)
Jenis event. Nilai tetap: conversation.item.delete.
item_idstring(wajib)
ID item percakapan yang akan dihapus.
{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

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 hasil function_call_output sebelum 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_started dan response.done).
Bidang opsional 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)
Jenis event. Nilai tetap: response.create.
responseobject(opsional)
Mengganti default sesi untuk putaran inferensi saat ini. Jika tidak disediakan, konfigurasi sesi saat ini yang digunakan.
modalitiesarray(opsional)
Mengganti modalitas output untuk putaran ini. Nilai yang valid sama dengan modalities pada session.update.
voicestring(opsional)
Mengganti suara TTS untuk putaran ini.
{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

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)
Jenis event. Nilai tetap: response.cancel.
{
    "type": "response.cancel"
}