Event klien WebSocket CosyVoice - Alibaba Cloud Model Studio

run-task

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.

header object(wajib)

Properti

action string(wajib)

Jenis perintah. Atur ke run-task.

task_id string(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.

streaming string(wajib)

Atur ke duplex.

payload object(wajib)

Properti

task_group string(wajib)

Kelompok tugas. Atur ke audio.

task string(wajib)

Jenis tugas. Atur ke tts.

function string(wajib)

Jenis fungsi. Atur ke SpeechSynthesizer.

model string(wajib)

Nama model.

input object(wajib)

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

parameters object(wajib)

Parameter sintesis suara.

Properti

text_type string(wajib)

Atur ke PlainText.

voice string(wajib)

Voice yang digunakan untuk sintesis suara.

System voices: Lihat Daftar Voice CosyVoice
Cloned voices: Voice kustom yang dibuat melalui voice cloning
Custom voices: Voice kustom yang dibuat melalui voice design

format string(opsional)

Format encoding audio.

Nilai yang valid:

pcm
wav
mp3 (default)
opus

sample_rate integer(opsional)

Laju sampel audio dalam Hz.

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

volume integer(opsional)

Tingkat volume.

Nilai default: 50.

Nilai yang valid: [0, 100].

rate float(opsional)

Laju bicara.

Nilai default: 1.0.

Nilai yang valid: [0.5, 2.0].

pitch float(opsional)

Pitch.

Nilai default: 1.0.

Nilai yang valid: [0.5, 2.0].

bit_rate integer(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_ssml boolean(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_enabled boolean(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, cosyvoice-v2, serta system voices yang ditandai sebagai didukung dalam Daftar Voice CosyVoice. Cloned voices dari model lain tidak mendukung fitur ini.

seed integer(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_hints array[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

instruction string(opsional)

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

enable_aigc_tag boolean(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.

CatatanHanya cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 yang mendukung fitur ini.

aigc_propagator string(opsional)

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

Nilai default: UID Alibaba Cloud.

CatatanHanya cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 yang mendukung fitur ini.

aigc_propagate_id string(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.

CatatanHanya cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 yang mendukung fitur ini.

hot_fix object(opsional)

Mengonfigurasi koreksi pelafalan dan penggantian teks yang diterapkan sebelum sintesis.

CatatanFitur ini tidak didukung oleh 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_filter boolean(opsional)

CatatanHanya 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": "cosyvoice-v3-plus",
        "parameters": {
            "text_type": "PlainText",
            "voice": "longanyang",
            "format": "mp3",
            "sample_rate": 22050,
            "volume": 50,
            "rate": 1.0,
            "pitch": 1.0,
            "enable_ssml": false
        },
        "input": {}
    }
}

continue-task

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.

header object(wajib)

Properti

action string(wajib)

Jenis perintah. Atur ke continue-task.

task_id string(wajib)

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

streaming string(wajib)

Atur ke duplex.

payload object(wajib)

Properti

input object(wajib)

Berisi teks yang akan disintesis.

text string(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

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.

header object(wajib)

Properti

action string(wajib)

Jenis perintah. Atur ke finish-task.

task_id string(wajib)

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

streaming string(wajib)

Atur ke duplex.

payload object(wajib)

Properti

input object(wajib)

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

directive string(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): Model CosyVoice memerlukan versi v2 atau lebih baru.
Singapura: 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"
        }
    }
}