Skip to main content
WebSocket

Ikhtisar koneksi WebSocket

Pelajari tentang endpoint WebSocket, autentikasi, alur interaksi Realtime dan Inferensi, serta event spesifik model.

Prasyarat

  • Aktifkan model atau aplikasi target dan konfirmasi wilayah yang didukungnya.
  • Dapatkan API key untuk wilayah dan workspace yang akan Anda gunakan. Lihat Autentikasi token.
  • Dapatkan ID Workspace Anda jika Anda menggunakan domain spesifik workspace.
Untuk pemilihan protokol dan model yang didukung, lihat Ikhtisar Realtime API.

Header permintaan

Atur Authorization dalam permintaan handshake WebSocket. Gunakan header lain seperti yang dijelaskan dalam referensi parameter model target.
HeaderWajibDeskripsi
AuthorizationYaBerikan API key sebagai Bearer <API_KEY>.
user-agentTidakMengidentifikasi klien.
X-DashScope-WorkSpaceSpesifik modelMenentukan ID workspace. Lihat referensi header spesifik model untuk penggunaannya.
X-DashScope-DataInspectionSpesifik modelMengonfigurasi inspeksi data. Lihat referensi header spesifik model untuk nilai yang didukung dan penerapannya.

Endpoint

Gunakan wss:// dan pilih jalur API serta lokasi nama model untuk model target Anda. Tabel di bawah ini mencantumkan metode koneksi berdasarkan model. Untuk model dan wilayah yang didukung, lihat dokumentasi model yang sesuai.
Keluarga modelPath APILokasi nama model
Qwen-Omni-Realtime/api-ws/v1/realtimeParameter kueri URL model
Qwen-Audio-TTS/CosyVoice/api-ws/v1/inferencepayload.model dalam run-task
Qwen-TTS-Realtime/api-ws/v1/realtimeParameter kueri URL model
Qwen-Audio-ASR/Fun-ASR/Paraformer/api-ws/v1/inferencepayload.model dalam run-task
Qwen-ASR-Realtime/api-ws/v1/realtimeParameter kueri URL model
Qwen-Audio-Realtime/api-ws/v1/realtimeParameter kueri URL model
Qwen-LiveTranslate-Realtime/api-ws/v1/realtimeParameter kueri URL model
Domain spesifik workspace:
WilayahDomain spesifik workspace
Tiongkok (Beijing){WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapura{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Ganti {WorkspaceId} dengan ID workspace Anda. Contoh: 
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtime
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference
Qwen-TTS-Realtime juga mendukung domain publik dashscope.aliyuncs.com untuk Beijing dan dashscope-intl.aliyuncs.com untuk Singapura, dengan jalur /api-ws/v1/realtime yang sama. API key harus sesuai dengan wilayahnya.

Alur interaksi umum

/api-ws/v1/realtime menggunakan protokol berbasis sesi, sedangkan /api-ws/v1/inference menggunakan protokol berbasis tugas.

Protokol waktu nyata

Setelah terhubung, klien mengonfigurasi sesi dengan session.update dan menunggu session.updated sebelum mengirimkan input. Model target menentukan cara melakukan commit input, memicu respons, dan mengakhiri sesi.
  1. Klien → Realtime API: Jabat tangan WebSocket dengan Authorization dan model.
  2. Realtime API → Klien: HTTP 101 dan session.created.
  3. Klien → Realtime API: session.update. Realtime API → Klien: session.updated.
  4. Dalam loop input/output, pilih cabang input: untuk audio, Klien → Realtime API: input_audio_buffer.append; untuk input teks Qwen-TTS, Klien → Realtime API: input_text_buffer.append.
  5. Commit manual opsional: Klien → Realtime API: input_audio_buffer.commit atau input_text_buffer.commit, dipilih sesuai dengan jenis input.
  6. Untuk model yang memerlukan respons eksplisit, Klien → Realtime API: response.create.
  7. Realtime API → Klien: peristiwa teks / response.audio.delta.
  8. Penyelesaian respons opsional, tidak termasuk model khusus ASR: Realtime API → Klien: response.done. Loop input/output dapat dilanjutkan.
  9. Untuk model yang mendukung peristiwa selesai, Klien → Realtime API: session.finish; Realtime API → Klien: session.finished.
  10. Klien → Realtime API: Menutup koneksi WebSocket.
Langkah-langkah terperinci
  1. Hubungkan: Tentukan model dalam parameter kueri model URL dan sertakan API key dalam header permintaan. Setelah handshake berhasil, server mengirimkan session.created.
  2. Konfigurasikan sesi: Kirim session.update untuk mengonfigurasi format audio yang didukung, modalitas output, suara, atau parameter deteksi ucapan, lalu tunggu session.updated. Lihat referensi event klien spesifik model untuk parameter sesi yang didukung.
  3. Kirim input: Kirim audio berkode Base64 dengan input_audio_buffer.append. Untuk Qwen-TTS, kirim teks dengan input_text_buffer.append. Model yang mendukung input gambar menggunakan input_image_buffer.append; ikuti persyaratan waktu gambar dan audio model tersebut.
  4. Commit dan terima hasil: Dalam mode otomatis, server memicu pemrosesan. Dalam mode manual, kirim input_audio_buffer.commit atau input_text_buffer.commit sesuai dengan jenis input. Apakah response.create juga diperlukan, dan event hasil mana yang harus ditangani, bergantung pada model. Lihat perbandingan di bawah ini.
  5. Akhiri sesi: Untuk model yang mendukung event selesai, kirim session.finish dan tunggu session.finished serta hasil yang tersisa. Untuk model lainnya, tutup WebSocket setelah menerima hasil. response.done menandai akhir dari satu respons, bukan koneksi. Untuk model khusus ASR, event penyelesaian transkripsi menandai akhir dari pengenalan.

Protokol inferensi

Klien mengirim run-task dan menunggu task-started sebelum mentransmisikan input. Pengenalan ucapan menggunakan frame audio biner; sintesis ucapan mengirim teks dengan continue-task. Saat input berakhir, kirim finish-task dan tunggu task-finished.
  1. Klien → Inference API: Jabat tangan WebSocket dengan Authorization.
  2. Inference API → Klien: HTTP 101.
  3. Klien → Inference API: run-task dengan payload.model dan task_id. Inference API → Klien: task-started.
  4. Dalam loop input/output, cabang pengenalan ucapan mengirim frame audio biner dari Klien ke Inference API. Inference API mengembalikan result-generated ke Klien.
  5. Dalam cabang sintesis ucapan, Klien → Inference API: continue-task dengan teks dan task_id. Inference API → Klien: frame audio biner dan result-generated jika disediakan.
  6. Ketika loop input/output berakhir, Klien → Inference API: finish-task dengan task_id yang sama.
  7. Inference API → Klien: Hasil yang tersisa dan task-finished.
  8. Klien → Inference API: Menutup atau menggunakan kembali koneksi sesuai dukungan model.
Langkah-langkah terperinci
  1. Hubungkan: Gunakan /api-ws/v1/inference dan sertakan API key dalam header permintaan.
  2. Mulai tugas: Kirim run-task, tentukan model dalam payload.model dan parameter seperti format input. Buat header.task_id yang unik dan tunggu task-started.
  3. Kirim input dan terima hasil:
    • Pengenalan ucapan: Kirim frame audio biner dan terima hasil pengenalan melalui result-generated.
    • Sintesis ucapan: Kirim teks dalam payload.input.text dari continue-task dan terima frame audio biner. Model juga dapat mengembalikan informasi seperti stempel waktu melalui result-generated.
  4. Selesaikan tugas: Setelah mengirim finish-task, terus terima hasil yang tersisa hingga task-finished tiba. Semua event run-task, continue-task, dan finish-task untuk tugas yang sama harus menggunakan header.task_id yang sama. Kemudian tutup koneksi, atau gunakan kembali sesuai dukungan model.

Perbedaan model

Model waktu nyata

Tabel di bawah ini merangkum pemicu input dan pengakhiran sesi. Untuk semua jenis VAD yang didukung, format audio, dan nilai parameter lainnya, lihat referensi event spesifik model.
ModelPemicu input dan responsPengakhiran
Qwen3.8-Omni / Qwen3.5-OmniMode VAD memicu respons secara otomatis. Dalam mode Manual, kirim input_audio_buffer.commit diikuti oleh response.create.Tutup koneksi setelah menerima hasil.
Qwen-TTS-Realtimeserver_commit melakukan commit teks secara otomatis. Dalam mode commit, kirim input_text_buffer.commit; response.create tidak diperlukan.session.finish → session.finished
Qwen-ASR-RealtimeMode VAD memproses input secara otomatis. Dalam mode Manual, kirim input_audio_buffer.commit; response.create tidak diperlukan.session.finish → session.finished
Qwen-Audio-RealtimeMode otomatis mendeteksi giliran bicara di server. Dalam mode Manual, kirim input_audio_buffer.commit diikuti oleh response.create.Tutup koneksi setelah menerima hasil.
Qwen3.8-LiveTranslateKonfigurasikan modalitas output dengan output_modalities dan deteksi giliran bicara dengan audio.input.turn_detection. Streaming audio dan kirim session.finish saat input berakhir.session.finish → session.finished
Qwen3.5-LiveTranslateKonfigurasikan sesi dengan modalities dan turn_detection. Dalam mode Manual, input_audio_buffer.commit memicu respons tanpa response.create.session.finish → session.finished
Event output utama tercantum di bawah ini. Event yang dikembalikan bergantung pada modalitas output yang dikonfigurasi.
ModelEvent output utama
Qwen-Omni-Realtimeresponse.text.delta / response.audio_transcript.delta / response.audio.delta / response.done
Qwen-TTS-Realtimeresponse.audio.delta / response.done
Qwen-ASR-Realtimeconversation.item.input_audio_transcription.text / conversation.item.input_audio_transcription.completed
Qwen-Audio-Realtimeresponse.audio_transcript.delta / response.audio.delta / response.done
Qwen3.8-LiveTranslateresponse.text.delta / response.audio_transcript.delta / response.audio.delta / response.done
Qwen3.5-LiveTranslateresponse.text.text / response.audio_transcript.text / response.audio.delta / response.done
Nama event terjemahan bergantung pada versi model: Qwen3.8-LiveTranslate menggunakan .delta, sedangkan Qwen3.5-LiveTranslate menggunakan .text. Misalnya, transkrip audio yang diterjemahkan masing-masing menggunakan response.audio_transcript.delta dan response.audio_transcript.text.

Model inferensi

Qwen-Audio-TTS/CosyVoice menggunakan alur tugas run-task → task-started → continue-task → finish-task → task-finished. Pengenalan ucapan Qwen-Audio-ASR/Fun-ASR/Paraformer mengirimkan frame audio biner setelah task-started. Kedua jenis tersebut melaporkan kesalahan tugas melalui task-failed.

Panduan integrasi spesifik model

Omni waktu nyata

Sintesis ucapan real-time

Qwen-Audio-TTS

CosyVoice

Qwen-TTS-Realtime

Sambert

Pengenalan ucapan real-time

Qwen-Audio-ASR-Message

Qwen-Audio-ASR-Streaming

Fun-ASR-Realtime

Qwen-ASR-Realtime

Paraformer

Percakapan suara real-time

Qwen-Audio-Realtime

Terjemahan audio dan video real-time

Qwen-Livetranslate-Realtime

Penanganan error

  • Kegagalan handshake: Gunakan status HTTP dan pesan kesalahan untuk memeriksa endpoint, API key, workspace, dan izin model. Untuk 401/403, periksa autentikasi terlebih dahulu.
  • Model tidak tersedia atau belum diaktifkan: Verifikasi nama model, aktivasi layanan, dan wilayah.
  • Kesalahan waktu nyata: Tangani event error dan baca jenis serta pesannya. Sesuaikan jenis event atau parameter dalam permintaan berdasarkan pesan kesalahan tersebut.
  • Kesalahan inferensi: Event task-failed menunjukkan bahwa tugas telah gagal. Baca header.error_code dan header.error_message untuk mengetahui penyebabnya.
Setelah memperbaiki konfigurasi atau menangani gangguan jaringan, hubungkan kembali dan konfigurasikan sesi baru atau mulai tugas baru sesuai dengan persyaratan protokol. Lihat Kode kesalahan.
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