Client events - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

Topik ini menjelaskan client events untuk API qwen3.5-livetranslate-flash-realtime.

Referensi: Terjemahan audio dan video Real-time - Qwen.

session.update

Kirim event ini setelah koneksi WebSocket terbentuk untuk memperbarui konfigurasi sesi default. Server memvalidasi parameter dan mengembalikan error (jika tidak valid) atau konfigurasi yang diperbarui (jika valid).

typestring(Required)

Jenis event. Harus diatur ke session.update.

sessionobject(Optional)

Konfigurasi sesi.

Properties

modalitiesarray(Optional)

Modalitas output. Nilai yang valid:

["text"]

Hanya menghasilkan output teks.
["text","audio"] (Default)

Menghasilkan output teks dan audio.

voicestring(Optional)

Voice untuk audio yang dihasilkan. Saat voice cloning dinonaktifkan, atur nilai ini ke voice preset sistem. Nilai yang valid: Voice yang didukung. Nilai default: Tina untuk Qwen3.5-LiveTranslate-Flash-Realtime, atau Cherry untuk Qwen3-LiveTranslate-Flash-Realtime.

Saat enable_voice_clone bernilai true, nilai voice bergantung pada pengaturan frequency. Saat frequency bernilai once atau always, atur nilainya ke default. Saat frequency bernilai never, atur nilainya ke ID voice yang sebelumnya telah Anda kloning. Menggunakan voice preset sistem dalam kasus ini akan menyebabkan error di server.

enable_voice_cloneboolean(Optional)

Menentukan apakah voice cloning diaktifkan. Nilai default: false. Saat diaktifkan, model akan mengkloning voice pembicara dari audio input untuk output terjemahan. Dalam hal ini, voice tidak lagi menerima voice preset sistem dan harus diatur ke default atau ID voice yang sebelumnya dibuat melalui Voice Clone API.

voice_clone_optionsobject(Optional)

Opsi kontrol voice cloning. Hanya berlaku saat enable_voice_clone bernilai true.

Properties

voice_clone_options.frequencystring(Optional)

Frekuensi voice cloning. Nilai yang valid:

never

Menonaktifkan voice cloning di sisi server dan menggunakan voice yang sebelumnya telah Anda kloning. Atur voice ke ID voice kloning Anda.
once

Mengkloning voice sekali di awal sesi dan menggunakan kembali voice tersebut untuk semua output selanjutnya. Cocok untuk skenario satu pembicara. Atur voice ke default.
always

Menkloning ulang voice secara real-time sebelum setiap output, menyesuaikan secara dinamis dengan audio input. Cocok untuk skenario multi-pembicara. Atur voice ke default.

sample_rateinteger(Optional)

Laju sampel audio input, dalam Hz. Nilai yang valid:

8000
16000 (Default)

input_audio_transcriptionobject(Optional)

Konfigurasi untuk audio input.

Properties

modelstring(Optional)

Model pengenalan suara. Jika dikonfigurasi, server mengembalikan hasil pengenalan (teks dalam bahasa sumber asli) dan terjemahan melalui event conversation.item.input_audio_transcription.text dan conversation.item.input_audio_transcription.completed.

Nilai yang valid: qwen3-asr-flash-realtime.

languagestring(Optional)

Bahasa sumber untuk terjemahan. Nilai yang valid: Bahasa yang didukung. Jika tidak ditentukan, model akan mendeteksi bahasa sumber secara otomatis.

input_audio_formatstring(Optional)

Format audio input. Nilai yang valid:

pcm (Default)

Data audio mentah tanpa kompresi.
opus

Kodek audio lossy dengan dukungan latensi rendah, cocok untuk skenario VoIP.

output_audio_formatstring(Optional)

Format audio output. Saat ini, parameter ini hanya dapat diatur ke pcm.

turn_detectionobject(Optional)

Konfigurasi Voice Activity Detection (VAD), digunakan untuk mengontrol cara deteksi awal dan akhir ucapan:

Diatur ke objek konfigurasi (default): Mengaktifkan mode VAD. Server secara otomatis mendeteksi awal dan akhir ucapan, melakukan commit buffer audio, dan memicu respons terjemahan. Klien tidak perlu mengirim event input_audio_buffer.commit.
Diatur ke null: Mengaktifkan mode Manual. Klien melakukan commit buffer audio secara manual dengan mengirim event input_audio_buffer.commit. Server secara otomatis mulai menghasilkan respons terjemahan setelah menerima commit tersebut.

Properties

typestring(Optional)

Jenis VAD. Harus diatur ke server_vad.

thresholdfloat(Optional)

Sensitivitas deteksi VAD. Nilai yang lebih rendah membuat suara pelan (termasuk kebisingan latar) lebih mudah dikenali sebagai ucapan; nilai yang lebih tinggi memerlukan ucapan yang lebih jelas dan keras untuk memicu deteksi.

Rentang nilai: [-1.0, 1.0]. Nilai default: 0.2.

silence_duration_msinteger(Optional)

Durasi minimum kesenyapan (dalam milidetik) yang diperlukan setelah ucapan berakhir. Setelah durasi ini terlampaui, server menentukan bahwa ucapan telah berakhir, secara otomatis melakukan commit buffer audio, dan memicu respons terjemahan.

Rentang nilai: [200, 6000]. Nilai default: 1000.

translationobject(Optional)

Konfigurasi terjemahan.

Properties

languagestring(Optional)

Bahasa target untuk terjemahan. Nilai yang valid: Bahasa yang didukung. Nilai default: en.

same_language_skip_optionsobject(Optional)

Konfigurasi output bahasa yang sama. Saat bahasa sumber dan target sama, layanan dapat melewatkan output teks, output audio, atau keduanya. Parameter ini hanya berlaku saat translation.language diatur ke zh atau en.

Properties

skip_textboolean(Optional)

Menentukan apakah output teks dilewati saat bahasa sumber dan target sama.

skip_audioboolean(Optional)

Menentukan apakah output audio dilewati saat bahasa sumber dan target sama.

corpusobject(Optional)

Konfigurasi hot-word untuk meningkatkan akurasi terjemahan istilah tertentu.

Properties

phrasesobject(Optional)

Pemetaan hot-word. Kunci adalah istilah dalam bahasa sumber, dan nilainya adalah terjemahannya dalam bahasa target.

Contoh: {"AI": "Artificial Intelligence"}

{
  "event_id": "event_ToPZqeobitzUJnt3QqtWg",
  "type": "session.update",
  "session": {
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "Cherry",
    "sample_rate": 16000,
    "input_audio_format": "pcm",
    "output_audio_format": "pcm",
    "input_audio_transcription": {
      "model": "qwen3-asr-flash-realtime",
      "language": "zh"
    },
    "translation": {
      "language": "en",
      "corpus": {
        "phrases": {
          "人工智能": "Artificial Intelligence",
          "机器学习": "Machine Learning"
        }
      }
    }
  }
}

Contoh dengan voice clone diaktifkan (frequency=once):

{
  "event_id": "event_ToPZqeobitzUJnt3QqtWg",
  "type": "session.update",
  "session": {
    "modalities": [
      "text",
      "audio"
    ],
    "voice": "default",
    "enable_voice_clone": true,
    "voice_clone_options": {
      "frequency": "once"
    },
    "sample_rate": 16000,
    "input_audio_format": "pcm",
    "output_audio_format": "pcm",
    "translation": {
      "language": "en"
    }
  }
}

Contoh dengan bahasa sumber dan target diatur ke bahasa Inggris serta output teks dan audio dilewati:

{
  "event_id": "event_xxx",
  "type": "session.update",
  "session": {
    "input_audio_transcription": {
      "language": "en"
    },
    "translation": {
      "language": "en",
      "same_language_skip_options": {
        "skip_text": true,
        "skip_audio": true
      }
    }
  }
}

input_audio_buffer.append

Menambahkan byte audio ke buffer audio input. Layanan menggunakan buffer ini untuk mendeteksi ucapan dan menentukan kapan harus mengirimkannya.

typestring(Required)

Jenis event. Harus diatur ke input_audio_buffer.append.

audiostring(Required)

Data audio yang dienkripsi Base64.

{
    "event_id": "event_xxx",
    "type": "input_audio_buffer.append",
    "audio": "xxx"
}

input_audio_buffer.commit

Menyimpan buffer audio input. Event ini hanya perlu dikirim dalam mode Manual (turn_detection diatur ke null). Dalam mode VAD, server melakukan commit secara otomatis dan klien tidak perlu mengirim event ini.

Saat menerima event ini, server mengembalikan event input_audio_buffer.committed sebagai konfirmasi dan secara otomatis mulai menghasilkan respons terjemahan (tidak diperlukan event tambahan untuk memicu respons). Jika buffer audio kosong, server mengembalikan event error.

typestring(Required)

Jenis event. Harus diatur ke input_audio_buffer.commit.

{
    "event_id": "event_xxx",
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

Menghapus data audio yang belum disimpan dari buffer audio input.

typestring(Required)

Jenis event. Harus diatur ke input_audio_buffer.clear.

{
    "event_id": "event_xxx",
    "type": "input_audio_buffer.clear"
}

input_image_buffer.append

Menambahkan data gambar ke buffer gambar dari file lokal atau aliran video real-time.

Batas input gambar:

Format gambar: JPG atau JPEG. Resolusi yang direkomendasikan untuk performa optimal: 480p atau 720p (maksimum: 1080p).
Ukuran gambar maksimum: 500 KB (sebelum enkode Base64).
Data gambar harus dikodekan dalam Base64.
Frekuensi maksimum: 2 gambar per detik.
Kirim minimal satu event input_audio_buffer.append sebelum mengirim input_image_buffer.append.

typestring(Required)

Jenis event. Harus diatur ke input_image_buffer.append.

imagestring(Required)

Data gambar yang dienkripsi Base64.

{
    "event_id": "event_xxx",
    "type": "input_image_buffer.append",
    "image": "xxx"
}

session.finish

Kirim event ini untuk mengakhiri sesi saat ini. Respons server:

Jika ucapan terdeteksi: Server menyelesaikan pengenalan ucapan, mengirim conversation.item.input_audio_transcription.completed dengan hasil pengenalan, lalu mengirim session.finished untuk menandakan akhir sesi.
Jika tidak ada ucapan yang terdeteksi: Server langsung mengirim session.finished.

Klien harus memutus koneksi setelah menerima session.finished.

typestring(Required)

Jenis event. Harus diatur ke session.finish.

{
    "event_id": "event_xxx",
    "type": "session.finish"
}