Skip to main content
Qwen-Audio-Realtime

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.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain berikut:
  • China (Beijing): dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya. Domain lama tetap berfungsi sepenuhnya.

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
  • China (Beijing)
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.
Gunakan protokol wss://. Atur Authorization di header permintaan. Masukkan nama model dalam parameter kueri URL model.

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.

Authorization diverifikasi selama handshake WebSocket. Jika Kunci API tidak valid atau tidak ada, handshake gagal dengan error HTTP 401/403.

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
  • User barge-in
Diagram berikut menggambarkan urutan interaksi khas dalam mode server_vad:
111
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.

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
  • User barge-in
  • Giliran tidak valid
Diagram berikut menggambarkan urutan interaksi khas dalam mode smart_turn:
111
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.

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).
voiceprint_audio_urls hanya dapat dikonfigurasi pada event session.update pertama. Bidang ini diabaikan pada panggilan session.update berikutnya.

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
  • User barge-in
Diagram berikut menggambarkan urutan interaksi khas dalam mode push-to-talk:
111
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.

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

turn_detection dan input_audio_format hanya dapat diubah sebelum audio pertama dikirim (status IDLE).

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

Penggunaan API
Generasi teks
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Real-time multimodal
Realtime API
Penyematan Teks
Lainnya Model
Toolkit/Framework
TokenPlan
Model production
Manajemen file
Penagihan
Manajemen Model
Lebih Banyak Tentang Model