Alibaba Cloud Model Studio:Referensi API WebSocket Realtime Qwen-Audio

API Realtime Qwen-Audio menyediakan kemampuan percakapan suara real-time melalui protokol WebSocket. Klien berinteraksi dengan server dengan mengirim dan menerima event JSON. API ini mendukung input audio, input teks, voice activity detection (VAD), serta output audio dan teks secara streaming.

Panduan pengguna: Realtime Audio Chat (Qwen-Audio-Realtime). Untuk penjelasan lengkap mengenai event klien dan event server, lihat Client events dan Server events.

Titik akhir layanan

URL WebSocket bersifat tetap sebagai berikut. Tentukan nama model menggunakan parameter kueri model (ganti <model_name> dengan nama model yang sebenarnya):

Singapura

wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>

Ganti {WorkspaceId} (termasuk tanda kurung kurawal) dengan workspace ID Anda yang sebenarnya.

China (Beijing)

wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>

Ganti {WorkspaceId} (termasuk tanda kurung kurawal) dengan workspace ID Anda yang sebenarnya.

Header permintaan

Sertakan header berikut dalam permintaan Anda:

Parameter	Type	Wajib	Deskripsi
Authorization	string	Ya	Token autentikasi dalam format Bearer <your_api_key>. Ganti <your_api_key> dengan Kunci API Anda yang sebenarnya.
user-agent	string	Tidak	Identifikasi klien untuk pelacakan permintaan di sisi server.
X-DashScope-WorkSpace	string	Tidak	ID ruang kerja Alibaba Cloud Model Studio.

Konsep utama

• Session: Satu koneksi WebSocket berkorespondensi dengan satu session, yang mempertahankan konfigurasi dan konteks percakapan.
• Conversation item: Sebuah pesan individual dalam percakapan, dipertahankan secara berurutan.
• Response: Output yang dihasilkan oleh satu inferensi model, berisi satu atau beberapa output item. Output item dapat berupa pesan asisten atau pemanggilan fungsi.
• Function calling: Output item yang dihasilkan model ketika memerlukan klien menjalankan fungsi tool. Setelah klien menjalankan tool tersebut, hasilnya dikirim kembali dalam function_call_output dan memicu inferensi berikutnya dengan response.create.
• Turn detection: Mengontrol kapan inferensi model dipicu.

Mode interaksi

API Realtime Qwen-Audio mendukung tiga mode interaksi, yang dikonfigurasi melalui parameter turn_detection.type pada event session.update:

Mode	turn_detection.type	Deskripsi	Kasus penggunaan
server_vad	server_vad	VAD di sisi server mendeteksi awal dan akhir ucapan, serta secara otomatis memicu inferensi.	Percakapan hands-free, asisten suara
smart_turn	smart_turn	Deteksi giliran cerdas yang menggabungkan analisis akustik dan semantik untuk menentukan batas giliran, bukan hanya berdasarkan sinyal suara. Suara non-semantik (seperti "uh" dan "ah") tidak memicu giliran atau mengganggu pemutaran.	Percakapan alami latensi rendah, interupsi berkualitas tinggi
push-to-talk	null	Klien secara manual mengirimkan audio dan memicu inferensi.	Push-to-talk, kontrol presisi

Alur interaksi

Untuk penjelasan lengkap mengenai event klien dan event server, lihat Client events dan Server events.

Mode server_vad

Server melakukan voice activity detection pada audio masuk dan secara otomatis memicu inferensi setelah mendeteksi akhir ucapan.

Cara mengaktifkan: Atur parameter turn_detection.type pada event session.update menjadi server_vad.

Giliran percakapan lengkap

Diagram berikut menggambarkan urutan interaksi khas dalam mode server_vad:

Interaksi berlangsung sebagai berikut:

1. Klien membuat koneksi WebSocket, dan server mengembalikan event session.created.
2. Klien mengirim session.update untuk mengonfigurasi parameter session, dan server mengembalikan session.updated.
3. Klien terus-menerus mengirim input_audio_buffer.append untuk mengalirkan audio data.
4. Server mendeteksi awal ucapan dan mengembalikan input_audio_buffer.speech_started. Server juga mengalirkan delta transkripsi ASR melalui conversation.item.input_audio_transcription.delta.
5. Server mendeteksi akhir ucapan dan mengembalikan input_audio_buffer.speech_stopped, input_audio_buffer.committed, dan conversation.item.created.
6. Server secara otomatis menghasilkan respons, mengalirkan delta teks dan audio (response.audio_transcript.delta, response.audio.delta), dan akhirnya mengembalikan response.done.

User barge-in

Jika VAD mendeteksi pengguna mulai berbicara saat model sedang memutar respons, server membatalkan respons saat ini (mengembalikan response.done dengan status cancelled), lalu memulai putaran baru input suara dan respons. Diagram berikut menggambarkan urutan interaksi user barge-in:

smart_turn mode

Mode smart_turn mendeteksi akhir ucapan dengan menggabungkan persepsi akustik dan pemahaman semantik, menyaring respons backchannel, kebisingan latar belakang, dan suara non-semantik lainnya. Suara non-semantik diteruskan sebagai event conversation.item.ambient_audio_transcription.delta tanpa memicu giliran percakapan.

Cara mengaktifkan: Atur parameter turn_detection.type pada event session.update menjadi smart_turn.

Giliran percakapan lengkap

Diagram berikut menggambarkan urutan interaksi khas dalam mode smart_turn:

Perbedaan utama dari mode server_vad:

• Suara non-semantik ("uh", "ah", dll.) tidak memicu inferensi. Sebagai gantinya, suara tersebut dikembalikan melalui event ambient_audio_transcription.
• Ucapan yang sebelumnya divalidasi dapat dibatalkan (input_audio_buffer.speech_stopped mengembalikan reason=turn_invalid), sehingga inferensi tidak dipicu.
• Saat menunggu input berikutnya dari pengguna, klien dapat secara eksplisit mengirim response.create untuk memicu inferensi.

User barge-in

Penanganan barge-in sebagian besar sama seperti pada mode server_vad. Diagram berikut menggambarkan urutan interaksi user barge-in:

Giliran tidak valid

Ucapan yang sebelumnya divalidasi dapat dibatalkan (input_audio_buffer.speech_stopped mengembalikan reason=turn_invalid), sehingga inferensi tidak dipicu. Klien harus terus mengirim audio dan menunggu ucapan valid berikutnya. Diagram berikut menggambarkan urutan interaksi giliran tidak valid:

Alur konfigurasi peningkatan speaker

Dalam mode smart_turn, ketika voiceprint_audio_urls disertakan dalam session.update pertama, server secara asinkron melakukan registrasi voiceprint (memuat fitur audio speaker target) dan memberi tahu klien mengenai progres registrasi melalui event. Registrasi voiceprint yang gagal tidak menghambat alur percakapan normal.

Urutan interaksi registrasi voiceprint adalah sebagai berikut:

1. Klien mengirim session.update dengan URL audio voiceprint dalam turn_detection.voiceprint_audio_urls. Server mengembalikan session.created.

2. Server segera memulai registrasi voiceprint secara asinkron dan mendorong voiceprint_audio_list.in_progress sebelum mengembalikan session.updated. Event ini membawa item_id yang secara unik mengidentifikasi tugas registrasi.

3. Server mengembalikan session.updated untuk mengonfirmasi bahwa konfigurasi session telah diterapkan.

4. Setelah registrasi selesai, server mendorong event terminal (dengan item_id yang sama seperti pada langkah 2):

   • Registrasi berhasil: voiceprint_audio_list.completed.
   • Registrasi gagal: voiceprint_audio_list.failed, dengan bidang reason yang menjelaskan kegagalan (misalnya, URL audio tidak dapat diunduh).

Mode push-to-talk

Klien secara manual mengontrol pengiriman audio dan pemicuan inferensi. Gunakan mode ini ketika Anda memerlukan kontrol presisi atas kapan audio dikirim dan inferensi dimulai.

Cara mengaktifkan: Atur parameter turn_detection pada event session.update menjadi null.

Giliran percakapan lengkap

Diagram berikut menggambarkan urutan interaksi khas dalam mode push-to-talk:

Interaksi berlangsung sebagai berikut:

1. Klien terus-menerus mengirim input_audio_buffer.append untuk mengalirkan audio data.
2. Setelah pengguna selesai berbicara, klien mengirim input_audio_buffer.commit untuk meng-commit buffer.
3. Klien mengirim response.create untuk secara manual memicu inferensi.
4. Server menghasilkan respons, mengalirkan teks dan audio.

User barge-in

Klien mengirim response.cancel untuk membatalkan respons saat ini, dan server mengembalikan response.done (dengan status cancelled dan alasan client_cancelled). Diagram berikut menggambarkan urutan interaksi user barge-in:

Batasan operasi mode

Operasi	push-to-talk	server_vad	smart_turn
session.update	Semua parameter dapat diubah dalam status IDLE; beberapa dibatasi dalam status non-IDLE	Semua parameter dapat diubah dalam status IDLE; beberapa dibatasi dalam status non-IDLE	Semua parameter dapat diubah dalam status IDLE; beberapa dibatasi dalam status non-IDLE
input_audio_buffer.append	Diizinkan	Diizinkan	Diizinkan
input_audio_buffer.commit	Diizinkan	Diabaikan	Diabaikan
input_audio_buffer.clear	Diizinkan	Diabaikan	Diabaikan
response.create	Diizinkan. Audio harus dikomit terlebih dahulu melalui input_audio_buffer.commit. Tidak diizinkan saat respons sedang dihasilkan.	Diizinkan saat tidak ada respons yang sedang dihasilkan; tidak diizinkan saat respons sedang dihasilkan	Diizinkan saat menunggu input berikutnya dari pengguna; tidak diizinkan selama giliran aktif (dari input_audio_buffer.speech_started hingga response.done)
response.cancel	Diizinkan (selama inferensi)	Diizinkan (selama inferensi)	Diizinkan (selama inferensi)
conversation.item.create/delete/retrieve	Diizinkan	Diizinkan	Diizinkan

Penanganan error

Type	Perilaku	Contoh
Error klien (invalid_request_error)	Koneksi tetap terbuka; klien menerima event error	Parameter tidak valid, status tidak diizinkan, item_id duplikat
Error server (server_error)	Koneksi dihentikan	Kegagalan koneksi LLM, kegagalan penyimpanan