Event klien WebSocket Qwen-Audio-TTS/CosyVoice - Alibaba Cloud Model Studio

Panduan pengguna: Untuk pengenalan model dan rekomendasi pemilihan, lihat Speech synthesis.

run-task

Deskripsi: Memulai tugas sintesis suara serta mengonfigurasi model, voice, sample rate, dan parameter lainnya.

Kapan dikirim: Segera setelah koneksi WebSocket terbentuk.

Event respons: Server mengembalikan event task-started. Tunggu event ini sebelum mengirim perintah berikutnya.

headerobject(wajib)

Properti

actionstring(wajib)

Jenis perintah. Atur ke run-task.

task_idstring(wajib)

ID tugas yang dihasilkan klien dalam format UUID. ID ini menghubungkan event-event berikutnya dan harus sesuai dengan task_id pada perintah continue-task dan finish-task.

streamingstring(wajib)

Atur ke duplex.

payloadobject(wajib)

Properti

task_groupstring(wajib)

Kelompok tugas. Atur ke audio.

taskstring(wajib)

Jenis tugas. Atur ke tts.

functionstring(wajib)

Jenis fungsi. Atur ke SpeechSynthesizer.

modelstring(wajib)

Nama model.

inputobject(wajib)

Atur ke objek kosong {}. Kirim teks yang akan disintesis melalui perintah continue-task.

parametersobject(wajib)

Parameter sintesis suara.

Properti

text_typestring(wajib)

Atur ke PlainText.

voicestring(wajib)

Voice yang digunakan untuk sintesis suara.

System voices: Lihat Daftar voice Qwen-Audio-TTS, Daftar Voice CosyVoice
Cloned voices: Voice kustom yang dibuat melalui voice cloning
Custom voices: Voice kustom yang dibuat melalui voice design

formatstring(opsional)

Format encoding audio.

Nilai yang valid:

pcm
wav
mp3 (default)
opus

sample_rateinteger(opsional)

Laju sampel audio dalam Hz.

Nilai yang valid: 8000, 16000, 22050 (default), 24000, 44100, 48000.

volumeinteger(opsional)

Tingkat volume.

Nilai default: 50.

Nilai yang valid: [0, 100].

ratefloat(opsional)

Laju bicara.

Nilai default: 1.0.

Nilai yang valid: [0.5, 2.0].

pitchfloat(opsional)

Pitch.

Nilai default: 1.0.

Nilai yang valid: [0.5, 2.0].

bit_rateinteger(opsional)

Laju bit audio dalam kbps. Saat format audio adalah mp3 atau opus, gunakan bit_rate untuk menyesuaikan laju bit.

Nilai default: 32.

Nilai yang valid: [6, 510].

enable_ssmlboolean(opsional)

Menentukan apakah SSML diaktifkan.

Nilai default: false.

Saat diatur ke true, hanya satu perintah continue-task yang diperbolehkan.

Untuk batasan penggunaan SSML (model, voice, dan API yang didukung), lihat Batasan.

word_timestamp_enabledboolean(opsional)

Menentukan apakah timestamp tingkat kata diaktifkan.

Nilai default: false.

Hanya tersedia dalam mode keluaran streaming. Voice yang didukung: cloned voices dari cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2, serta system voices yang ditandai sebagai didukung dalam Daftar voice Qwen-Audio-TTS, Daftar Voice CosyVoice. Cloned voices dari model lain tidak mendukung fitur ini.

seedinteger(opsional)

Seed acak untuk mengontrol variasi dalam output sintesis. Saat versi model, teks, voice, dan parameter lainnya tidak berubah, penggunaan seed yang sama menghasilkan output identik.

Nilai default: 0.

Nilai yang valid: [0, 65535].

language_hintsarray[string](opsional)

Penting

Parameter ini berupa array, tetapi versi saat ini hanya memproses elemen pertama. Kirim satu nilai saja.
Parameter ini menentukan bahasa target untuk sintesis suara. Parameter ini tidak terkait dengan bahasa sampel audio yang digunakan dalam voice cloning. Untuk mengatur bahasa sumber pada tugas cloning, lihat referensi API voice cloning.

Menentukan bahasa target untuk sintesis suara guna meningkatkan kualitas output.

Saat pelafalan angka, ekspansi singkatan, pembacaan simbol, atau sintesis bahasa minoritas tidak sesuai harapan, gunakan parameter ini. Contohnya:

Pelafalan angka tidak sesuai: "hello, this is 110" dibaca sebagai "hello, this is one zero" alih-alih pelafalan Mandarin yang diharapkan
Pelafalan simbol tidak akurat: "@" dibaca sebagai ekuivalen Mandarin alih-alih "at"
Kualitas sintesis bahasa minoritas buruk dengan hasil tidak alami

Nilai yang valid:

zh: Tionghoa
en: Inggris
fr: Prancis
de: Jerman
ja: Jepang
ko: Korea
ru: Rusia
pt: Portugis
th: Thai
id: Bahasa Indonesia
vi: Vietnam
es: Spanyol
it: Italia
ms: Malaysia
fil: Filipino
ar: Arab

instructionstring(opsional)

Mengatur instruksi untuk mengontrol dialek, emosi, atau karakter suara selama sintesis. Untuk penggunaan detail, lihat Kontrol instruksi.

enable_aigc_tagboolean(opsional)

Menentukan apakah watermark AIGC disematkan ke dalam audio yang dihasilkan. Saat diatur ke true, watermark disematkan ke file audio dengan format yang didukung (wav/mp3/opus).

Nilai default: false.

Hanya qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2 yang mendukung fitur ini.

aigc_propagatorstring(opsional)

Mengatur bidang ContentPropagator dalam watermark AIGC, yang mengidentifikasi propagator konten. Hanya berlaku saat enable_aigc_tag bernilai true.

Nilai default: UID Alibaba Cloud.

Hanya qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2 yang mendukung fitur ini.

aigc_propagate_idstring(opsional)

Mengatur bidang PropagateID dalam watermark AIGC, yang secara unik mengidentifikasi aksi propagasi tertentu. Hanya berlaku saat enable_aigc_tag bernilai true.

Nilai default: ID permintaan dari permintaan sintesis suara saat ini.

Hanya qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2 yang mendukung fitur ini.

hot_fixobject(opsional)

Mengonfigurasi koreksi pelafalan dan penggantian teks yang diterapkan sebelum sintesis.

Fitur ini tidak didukung oleh qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, atau cosyvoice-v2.

Parameter:

pronunciation: Pelafalan kustom. Menentukan anotasi pinyin untuk kata-kata guna memperbaiki pelafalan default yang tidak akurat.
replace: Penggantian teks. Mengganti kata-kata tertentu dengan teks target sebelum sintesis. Teks yang diganti digunakan sebagai input sintesis sebenarnya.

Contoh:

"hot_fix": {
  "pronunciation": [
    {"weather": "tian1 qi4"}
  ],
  "replace": [
    {"today": "gold day"}
  ]
}

enable_markdown_filterboolean(opsional)

PentingHanya cloned voices dari cosyvoice-v3-flash yang mendukung fitur ini.

Menentukan apakah penyaringan Markdown diaktifkan. Saat diaktifkan, sistem secara otomatis menghapus simbol markup Markdown dari teks input sebelum sintesis, sehingga simbol tersebut tidak ikut dibacakan.

Nilai default: false.

Nilai yang valid:

true: Aktifkan penyaringan Markdown
false: Nonaktifkan penyaringan Markdown

{
    "header": {
        "action": "run-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "task_group": "audio",
        "task": "tts",
        "function": "SpeechSynthesizer",
        "model": "qwen-audio-3.0-tts-flash",
        "parameters": {
            "text_type": "PlainText",
            "voice": "longanlingxi",
            "format": "mp3",
            "sample_rate": 22050,
            "volume": 50,
            "rate": 1.0,
            "pitch": 1.0,
            "enable_ssml": false
        },
        "input": {}
    }
}

continue-task

Deskripsi: Mengirim teks yang akan disintesis, baik sekaligus maupun dalam beberapa segmen.

Kapan dikirim: Setelah menerima event task-started dari server.

Batasan:

Maksimal 20.000 karakter per pesan
Maksimal 200.000 karakter secara kumulatif
Interval pengiriman tidak boleh melebihi 23 detik; jika tidak, koneksi akan timeout.

headerobject(wajib)

Properti

actionstring(wajib)

Jenis perintah. Atur ke continue-task.

task_idstring(wajib)

ID tugas dalam format UUID. Harus sesuai dengan task_id pada run-task.

streamingstring(wajib)

Atur ke duplex.

payloadobject(wajib)

Properti

inputobject(wajib)

Berisi teks yang akan disintesis.

textstring(wajib)

Teks yang akan disintesis. Maksimal 20.000 karakter per pesan dan 200.000 karakter secara kumulatif.

{
    "header": {
        "action": "continue-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {
            "text": "Before my bed, moonlight shines bright, I suspect it's frost upon the ground."
        }
    }
}

finish-task

Deskripsi: Memberi tahu server bahwa seluruh teks telah dikirim dan meminta penyelesaian tugas.

Kapan dikirim: Segera setelah seluruh teks dikirim.

Event respons: Server mengembalikan event task-finished.

headerobject(wajib)

Properti

actionstring(wajib)

Jenis perintah. Atur ke finish-task.

task_idstring(wajib)

ID tugas dalam format UUID. Harus sesuai dengan task_id pada run-task.

streamingstring(wajib)

Atur ke duplex.

payloadobject(wajib)

Properti

inputobject(wajib)

Atur ke {} untuk penyelesaian tugas normal. Sertakan properti directive untuk membatalkan putaran sintesis saat ini.

directivestring(opsional)

Mengontrol cara tugas diakhiri. Saat ini hanya nilai cancel yang didukung. Jika diatur ke cancel, putaran sintesis saat ini akan dibatalkan dan server segera mengembalikan event task-finished tanpa menghasilkan audio tambahan.

Setelah pembatalan, Anda dapat memulai tugas sintesis baru pada koneksi WebSocket yang sama dengan mengirim event run-task baru tanpa perlu menyambung ulang.

PentingBatasan model:

China (Beijing): Semua model Qwen-Audio-TTS mendukung fitur ini. Model CosyVoice memerlukan versi v2 atau lebih baru.
Singapura: Semua model Qwen-Audio-TTS mendukung fitur ini. Model CosyVoice tidak mendukung fitur ini.

{
    "header": {
        "action": "finish-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {}
    }
}

Contoh pembatalan tugas:

{
    "header": {
        "action": "finish-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {
            "directive": "cancel"
        }
    }
}