Akses WebRTC Qwen-Audio-Realtime
WebRTC menggunakan track media untuk mengirim audio dan DataChannel untuk mengirim peristiwa model serta teks. Klien web dapat menggunakan API bawaan browser, sedangkan klien lain dapat menggunakan pustaka yang mendukung WebRTC standar. Model Studio tidak menyediakan SDK WebRTC khusus.
Dokumen ini menyediakan prosedur integrasi WebRTC untuk model ini beserta contoh lengkap di sisi browser.
Dokumen ini ditujukan untuk Qwen-Audio-Realtime. Petunjuk akses yang ada mencakup 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. Model contoh adalah
Browser mengirim Offer SDP ke AppServer bisnis. AppServer meneruskan permintaan berikut menggunakan API Key dan mengembalikan Answer SDP tanpa perubahan ke browser. API Key jangka panjang tidak diteruskan ke frontend.
Berikut adalah contoh lengkap di sisi browser. Pertama, implementasikan antarmuka
AppServer mengatur pertukaran SDP untuk model tujuan, wilayah, dan ruang kerja. Parameter berikut berlaku untuk koneksi Realtime standar. Untuk parameter khusus aplikasi, ikuti praktik terbaik yang sesuai.
Detail lengkap region, alamat, dan autentikasi tersedia dalam Autentikasi dan pertukaran SDP. Antarmuka AppServer bisnis diimplementasikan oleh pihak bisnis dan bukan bagian dari API SDK Model Studio.
Di web, buat
Arah dilihat dari sisi klien. Transceiver WebRTC menegosiasikan pengiriman dan penerimaan:
Misalnya, percakapan suara biasanya menggunakan audio dua arah. Offer SDP harus mencakup bagian media audio
Tabel ini menjelaskan arah media yang dibutuhkan aplikasi; tidak menjamin semua kombinasi dapat dinegosiasikan secara terpisah. Konfigurasi bergantung pada model tujuan dan kemampuan negosiasi server.
Negosiasikan arah yang diperlukan sebelum membuat Offer. Untuk model yang memerlukan konfirmasi inisialisasi, siapkan kemampuan pengiriman tanpa memasang trek yang diambil. Setelah model siap, gunakan
Contoh berikut menunjukkan suara dua arah. Dua sakelar dalam
Buat DataChannel sebelum membuat Offer agar SDP menyertakan negosiasi saluran data. Untuk cara klien dan server menangani pembuatan saluran, lihat Mengirim dan menerima peristiwa melalui saluran data.
DataChannel mengirim inisialisasi model, teks, dan peristiwa kontrol, serta menerima hasil, status, dan error model. Track media mengirim audio.
Contoh lengkap membuat saluran peristiwa klien dan mendaftarkan callback saluran sisi server sebelum membuat Offer.
Selesaikan koneksi dengan urutan berikut:
Pantau
Saat koneksi dan kanal peristiwa tersedia, inisialisasi model tujuan sesuai protokolnya. Simpan peristiwa inisialisasi server dan gabungkan dengan status kanal untuk melanjutkan alur; jangan menganggap urutan kedatangan callback selalu tetap.
Misalnya, saat mengonfigurasi model dengan
Contoh berikut menunjukkan alur
Setelah model siap, pasang track audio uplink yang diperlukan. Tangani output model melalui callback track jarak jauh dan terus parse peristiwa yang dikembalikan DataChannel.
Saat koneksi tidak diperlukan lagi, hentikan trek pengambilan lokal milik aplikasi, tutup DataChannel dan
Pastikan saluran berstatus
Gunakan fungsi pengikatan yang sama untuk kanal buatan klien dan server. Fungsi ini menangani transport dan penguraian JSON;
Ikuti juga aturan berikut:
Cakupan penggunaan
Dokumen ini ditujukan untuk Qwen-Audio-Realtime. Petunjuk akses yang ada mencakup 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. Model contoh adalah qwen-audio-3.1-realtime-plus.
- Gunakan API Key dan ID ruang kerja yang sesuai dengan wilayah dan ruang kerja yang dipilih.
- Domain Beijing:
{WorkspaceId}.cn-beijing.maas.aliyuncs.com; domain Singapura:{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com. - Simpan API Key jangka panjang di sisi server dan jangan menyertakannya dalam aplikasi browser atau seluler. Untuk cara membuat API Key sementara dan izinnya, lihat Membuat API Key sementara.
Autentikasi dan pertukaran SDP
Browser mengirim Offer SDP ke AppServer bisnis. AppServer meneruskan permintaan berikut menggunakan API Key dan mengembalikan Answer SDP tanpa perubahan ke browser. API Key jangka panjang tidak diteruskan ke frontend.
- Metode:
POST
POST
https://WorkspaceId.cn-beijing.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plusPOST
https://WorkspaceId.ap-southeast-1.maas.aliyuncs.com/api/v1/webrtc/realtime?model=qwen-audio-3.1-realtime-plus- Header permintaan:
Authorization: Bearer <API_KEY>,Content-Type: application/sdp - Isi permintaan: string Offer SDP.
- Respons berhasil: HTTP 200 dengan Answer SDP dalam isi respons. Kegagalan mengembalikan 4xx.
/api/realtime/sdp adalah antarmuka khusus yang dibuat oleh AppServer bisnis. Antarmuka ini harus mengimplementasikan proses penerusan di atas dan bukan URL yang disediakan oleh Model Studio.
Alur kerja

- Siapkan API key dan parameter model tujuan di AppServer.
- Buat objek koneksi klien dan daftarkan callback.
- Atur arah media dan DataChannel tanpa memasang trek media upstream.
- Tukarkan SDP melalui AppServer dan tunggu koneksi serta kanal peristiwa siap.
- Konfigurasikan model sesuai protokolnya. Pasang trek media upstream yang diperlukan setelah konfirmasi.
- Hentikan pengambilan, tutup koneksi, dan lepas sumber daya setelah interaksi selesai.
- Audio dikirim melalui track media WebRTC. Aplikasi bertanggung jawab memperoleh track audio lokal, mengikat pemutar jarak jauh, serta mengirim dan menerima pesan DataChannel sesuai definisi peristiwa model tujuan.
- Autentikasi WebRTC berlangsung saat pertukaran SDP; token AOQ tidak diperlukan. Proksikan autentikasi dan SDP melalui AppServer agar API key jangka panjang tidak berada dalam kode frontend.
-
Koneksi yang berhasil menunjukkan bahwa saluran transmisi telah terbentuk, tetapi tidak berarti model telah selesai diinisialisasi. Saat menggunakan
qwen-audio-3.1-realtime-pluspada halaman ini, mulai media uplink yang diperlukan hanya setelah mengirimsession.updatedan menerimasession.updated.
Contoh lengkap
Berikut adalah contoh lengkap di sisi browser. Pertama, implementasikan antarmuka /api/realtime/sdp pada AppServer bisnis seperti dijelaskan dalam Autentikasi dan pertukaran SDP. Kemudian buka halaman HTML ini dari origin yang sama dengan AppServer bisnis, dengan protokol, host, dan port yang sama. Misalnya, halaman dan /api/realtime/sdp sama-sama dilayani oleh http://localhost:3000. Server menyimpan API Key dan meneruskan SDP. Jangan sertakan API Key jangka panjang di halaman. Klik “Start” untuk membuat koneksi dan “End” untuk melepas sumber daya setelah interaksi selesai. Contoh ini membuat satu koneksi pada satu waktu. Muat ulang halaman untuk memulai sesi lain.
1. Menyiapkan autentikasi dan parameter koneksi
AppServer mengatur pertukaran SDP untuk model tujuan, wilayah, dan ruang kerja. Parameter berikut berlaku untuk koneksi Realtime standar. Untuk parameter khusus aplikasi, ikuti praktik terbaik yang sesuai.
| Pengaturan | Nilai |
|---|---|
| Metode | POST |
| URL | https://{endpoint}/api/v1/webrtc/realtime?model={model_name} |
Content-Type | application/sdp |
Authorization | Bearer <API_KEY> |
| Isi permintaan | Offer SDP |
| Respons berhasil | Answer SDP |
2. Menginisialisasi objek koneksi dan mendaftarkan callback
Di web, buat RTCPeerConnection. Di platform lain, lakukan inisialisasi pustaka yang sesuai. Sebelum membuat koneksi, daftarkan handler berikut:
- Perubahan status koneksi: menentukan apakah koneksi berhasil, gagal, atau terputus.
- Pembentukan, pembukaan, pesan, dan penutupan DataChannel: membawa peristiwa model.
- Track media jarak jauh: menerima dan memutar audio, atau menangani media lain yang didukung aplikasi tujuan.
txt, sehingga callback datachannel harus ditangani.
3. Mengatur arah media dan DataChannel
Memilih arah audio
Arah dilihat dari sisi klien. Transceiver WebRTC menegosiasikan pengiriman dan penerimaan: sendrecv dua arah, sendonly hanya mengirim, dan recvonly hanya menerima. Kemampuan yang tersedia juga bergantung pada jawaban SDP server dan dukungan model.
| Arah | Konfigurasi |
|---|---|
| Mengirim audio | Menegosiasikan kemampuan pengiriman audio dan menyiapkan mikrofon atau track audio eksternal. Pasang track setelah model siap. |
| menerima audio— | Menegosiasikan kemampuan penerimaan audio dan mengikat pemutaran audio dalam callback track jarak jauh |
m=audio. Jangan menghapus bagian ini hanya karena bisnis tidak perlu memutar audio.
Arah media untuk model ini
| Model atau aplikasi | Mengirim audio | Menerima audio | Mengirim video | Menerima video |
|---|---|---|---|---|
| Qwen-Audio-Realtime | Aktifkan untuk input suara | Aktifkan untuk output suara | Tidak didukung | Tidak didukung |
Menyiapkan media tanpa mengirimnya
Negosiasikan arah yang diperlukan sebelum membuat Offer. Untuk model yang memerlukan konfirmasi inisialisasi, siapkan kemampuan pengiriman tanpa memasang trek yang diambil. Setelah model siap, gunakan replaceTrack pada sender terkait untuk memulai transmisi. Daftarkan penangan penerimaan media terlebih dahulu.
Konfigurasikan pengiriman dan penerimaan audio secara terpisah sesuai kebutuhan. Jangan menggabungkan pengaktifan mikrofon, pemutaran audio, dan inisialisasi model dalam satu operasi.
Contoh konfigurasi media
Contoh berikut menunjukkan suara dua arah. Dua sakelar dalam media mengontrol pengiriman dan penerimaan audio secara terpisah. addTransceiver menegosiasikan arah terlebih dahulu. Track yang ditangkap disimpan secara lokal hingga model siap, lalu dipasang ke sender.
Lihat kodenya dalam Contoh lengkap.
Membuat kanal peristiwa
Buat DataChannel sebelum membuat Offer agar SDP menyertakan negosiasi saluran data. Untuk cara klien dan server menangani pembuatan saluran, lihat Mengirim dan menerima peristiwa melalui saluran data.
DataChannel mengirim inisialisasi model, teks, dan peristiwa kontrol, serta menerima hasil, status, dan error model. Track media mengirim audio.
Contoh lengkap membuat saluran peristiwa klien dan mendaftarkan callback saluran sisi server sebelum membuat Offer.
4. Membuat koneksi
Selesaikan koneksi dengan urutan berikut:
- Panggil
createOfferdansetLocalDescription. - Kumpulkan informasi kandidat sesuai metode ICE yang didukung server. Dalam contoh ini, SDP lokal dikirim setelah pengumpulan ICE selesai.
- Kirim SDP lokal ke AppServer bisnis. AppServer menggunakan API Key untuk meminta antarmuka pertukaran SDP Model Studio.
- Periksa status HTTP. Jika berhasil, panggil
setRemoteDescriptionmenggunakan Answer SDP yang dikembalikan. - Tunggu hingga status koneksi menjadi berhasil dan pastikan DataChannel untuk mengirim peristiwa model telah terbuka.
setRemoteDescription hanya menunjukkan bahwa langkah negosiasi terkait telah selesai, bukan bukti langsung keberhasilan koneksi media. Peristiwa model juga tidak dapat dikirim saat DataChannel belum berstatus open.
Kode koneksi dan callback status
Pantau connectionstatechange untuk menentukan status koneksi dan icegatheringstatechange untuk menunggu SDP lokal lengkap. Inisialisasi model juga memerlukan open DataChannel serta peristiwa kesiapan model. Jangan hanya mengandalkan selesainya pertukaran SDP.
Contoh lengkap menyelesaikan pertukaran SDP melalui startSession() dan menangani hasil koneksi melalui callback status koneksi.
AppServer bisnis harus meneruskan Offer sesuai alamat dan header permintaan pada Bagian 1. API contoh diharapkan mengembalikan teks SDP biasa. Jangan meneruskan konten yang berisi header respons HTTP, log, atau pembungkus JSON langsung ke setRemoteDescription.
5. Bertukar peristiwa model dan media
Menginisialisasi model
Saat koneksi dan kanal peristiwa tersedia, inisialisasi model tujuan sesuai protokolnya. Simpan peristiwa inisialisasi server dan gabungkan dengan status kanal untuk melanjutkan alur; jangan menganggap urutan kedatangan callback selalu tetap.
Misalnya, saat mengonfigurasi model dengan session.update, susun peristiwa sesuai protokolnya dan tunggu konfirmasi konfigurasi sebelum mengirim input. Parameter seperti suara, modalitas output, VAD, dan laju sampling harus mengikuti dokumentasi model yang digunakan.
session.created menunjukkan pembuatan sesi dan tidak selalu berarti konfigurasi telah berlaku. Untuk model yang memerlukan konfirmasi konfigurasi sesi, tunggu session.updated.
Definisi peristiwa model tersedia dalam Peristiwa klien dan Peristiwa server. Tangani transmisi media dan mode yang tersedia sesuai penjelasan pada halaman ini.
Contoh peristiwa model
Audio dikirim melalui track media dan tidak menggunakan peristiwa pengiriman media WebSocket.
session.created → session.update → session.updated untuk qwen-audio-3.1-realtime-plus. Konfigurasikan bidang sesuai referensi peristiwa model. Pasang track audio uplink hanya setelah menerima session.updated yang mengonfirmasi bahwa konfigurasi selesai.
Lihat kodenya dalam Contoh lengkap.
Untuk model contoh qwen-audio-3.1-realtime-plus, setelah output audio diaktifkan, status pembuatan audio model dapat dipantau melalui response.audio.done. Peristiwa ini tidak menunjukkan bahwa pemutaran audio di klien telah selesai.
Memulai pengiriman dan penerimaan media
Setelah model siap, pasang track audio uplink yang diperlukan. Tangani output model melalui callback track jarak jauh dan terus parse peristiwa yang dikembalikan DataChannel.
-
Audio dikirim melalui trek media RTP; peristiwa
input_audio_buffer.appendtidak diperlukan. - DataChannel membawa teks serta peristiwa status, kontrol, dan kesalahan.
startSendingMedia() memasang track uplink dan ontrack menangani media yang diterima.
6. Mengakhiri interaksi dan melepas sumber daya
Saat koneksi tidak diperlukan lagi, hentikan trek pengambilan lokal milik aplikasi, tutup DataChannel dan RTCPeerConnection, lepas pemutar, dan hapus status aplikasi.
Hapus status kesiapan model setelah kegagalan atau koneksi terputus secara tidak terduga. Inisialisasi kembali model pada koneksi baru, bukan memakai ulang status sesi koneksi sebelumnya.
Dalam contoh lengkap, endSession() melepas koneksi dan sumber daya media.
Panggil endSession() saat pengguna mengeklik tombol akhir atau menutup halaman.
Mengirim dan menerima peristiwa melalui saluran data
Pastikan saluran berstatus open sebelum memanggil send dengan peristiwa yang diserialisasi. Parse pesan masuk dalam callback message, termasuk peristiwa pada saluran yang dibuat server.
Nama, bidang, parameter, dan waktu pengiriman peristiwa mengikuti Definisi peristiwa klien model target. Penguraian, perubahan status, hasil, dan penanganan kesalahan setelah menerima pesan mengikuti Definisi peristiwa server model. Kirim peristiwa inisialisasi sesuai persyaratan model; kirim peristiwa teks dan kontrol berikutnya sesuai kebutuhan aplikasi.
Contoh DataChannel
Gunakan fungsi pengikatan yang sama untuk kanal buatan klien dan server. Fungsi ini menangani transport dan penguraian JSON; handleModelEvent pada bagian 5 menangani semantik model. Gunakan sendModelEvent untuk inisialisasi, teks, atau kontrol hanya jika diizinkan protokol model.
Dalam contoh lengkap, sendModelEvent() dan bindDataChannel() mengirim dan menerima peristiwa.
Dalam contoh lengkap, tombol mulai memanggil startSession() dan tombol akhir memanggil endSession(). Keduanya adalah fungsi yang didefinisikan dalam contoh, bukan API bawaan WebRTC.
Definisi peristiwa Qwen-Audio-Realtime
| Model atau aplikasi | Peristiwa klien (kirim) | Peristiwa server (terima) |
|---|---|---|
| Qwen-Audio-Realtime | Peristiwa klien | Peristiwa server |
-
Gunakan bidang
typeperistiwa untuk mengidentifikasi peristiwa model, dan tangani pengenal terkait sesuai referensi peristiwa model ini. - Operasi yang diperlukan model, seperti konfirmasi inisialisasi, pengiriman input, pembatalan respons, dan penyelesaian tugas, ditangani dalam saluran Data sesuai protokolnya. Operasi ini merupakan semantik interaksi model dan berbeda dari pemutusan koneksi transport.
- Data audio dikirim melalui track media. Saat menggunakan referensi peristiwa model, ikuti halaman ini untuk enkapsulasi media dan mode interaksi yang tersedia. Jangan langsung menerapkan metode pengiriman media WebSocket.