Referensi peristiwa klien CosyVoice: bidang run-task, continue-task, dan finish-task, urutan pengiriman, serta peristiwa server terkait.
Alur peristiwa
- Kirim run-task untuk memulai dan mengonfigurasi tugas, lalu tunggu task-started.
- Setelah menerima
task-started, kirim teks melalui continue-task sambil menerima result-generated dan audio hasil sintesis. - Setelah semua teks terkirim, kirim finish-task dan terus terima sisa hasil serta audio hingga task-finished diterima. Tugas yang gagal mengembalikan task-failed.
result-generated mengembalikan metadata kalimat. Audio dikirim secara terpisah melalui frame biner WebSocket atau Audio Track AOQ. Untuk koneksi, autentikasi, dan transmisi audio, lihat API WebSocket atau akses AOQ.
run-task
Segera setelah koneksi terbentuk, klien mengirim run-task untuk memulai tugas sintesis ucapan dan mengatur model, suara, laju sampel, serta parameter lainnya.
headerobjectWajibactionstringWajibJenis perintah. Atur ke
run-task.task_idstringWajibID 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.streamingstringWajibAtur ke
duplex.payloadobjectWajibtask_groupstringWajibKelompok tugas. Atur ke
audio.taskstringWajibJenis tugas. Atur ke
tts.functionstringWajibJenis fungsi. Atur ke
SpeechSynthesizer.modelstringWajibNama model.
parametersobjectWajibParameter sintesis suara.
text_typestringWajibAtur ke
PlainText.voicestringWajibVoice 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
formatstringOpsionalFormat encoding audio.Nilai yang valid:
pcmwavmp3(default)opus
sample_rateintegerOpsionalLaju sampel audio dalam Hz.Nilai yang valid: 8000, 16000, 22050 (default), 24000, 44100, 48000.
volumeintegerOpsionalTingkat volume.Nilai default: 50.Nilai yang valid: [0, 100].
ratefloatOpsionalLaju bicara.Nilai default: 1.0.Nilai yang valid: [0.5, 2.0].
pitchfloatOpsionalPitch.Nilai default: 1.0.Nilai yang valid: [0.5, 2.0].
bit_rateintegerOpsionalLaju 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_ssmlbooleanOpsionalMenentukan apakah SSML diaktifkan.Nilai default: Untuk batasan penggunaan SSML (model, voice, dan API yang didukung), lihat Batasan.
false.Saat diatur ke
true, hanya satu perintah continue-task yang diperbolehkan.word_timestamp_enabledbooleanOpsionalMenentukan 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.
seedintegerOpsionalSeed 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- 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.
- Pelafalan angka tidak sesuai: "hello, this is 110" dibaca sebagai "hello, this is one 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
Nilai yang valid
zh: Tionghoaen: Inggrisfr: Prancisde: Jermanja: Jepangko: Korearu: Rusiapt: Portugisth: Thaiid: Bahasa Indonesiavi: Vietnames: Spanyolit: Italiams: Malaysiafil: Filipinoar: Arab
instructionstringOpsionalMengatur instruksi untuk mengontrol dialek, emosi, atau karakter suara selama sintesis. Untuk penggunaan detail, lihat Kontrol instruksi.
enable_aigc_tagbooleanOpsionalMenentukan 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 cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 yang mendukung fitur ini.
aigc_propagatorstringOpsionalMengatur bidang
ContentPropagator dalam watermark AIGC, yang mengidentifikasi propagator konten. Hanya berlaku saat enable_aigc_tag bernilai true.Nilai default: UID Alibaba Cloud.Hanya cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 yang mendukung fitur ini.
aigc_propagate_idstringOpsionalMengatur 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 cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 yang mendukung fitur ini.
hot_fixobjectOpsionalMengonfigurasi koreksi pelafalan dan penggantian teks yang diterapkan sebelum sintesis.Parameter:
Fitur ini tidak didukung oleh cosyvoice-v2.
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.
enable_markdown_filterbooleanOpsionalcosyvoice-v2 tidak mendukung fitur ini.
false.Nilai yang valid:true: Aktifkan penyaringan Markdownfalse: Nonaktifkan penyaringan Markdown
inputobjectWajibAtur ke objek kosong
{}. Kirim teks yang akan disintesis melalui perintah continue-task.Permintaan:
Respons:
continue-task
Setelah menerima task-started, klien mengirim continue-task untuk menyerahkan teks yang akan disintesis. Teks dapat dikirim sekaligus atau sebagai segmen secara berurutan.
headerobjectWajibactionstringWajibJenis perintah. Atur ke
continue-task.task_idstringWajibID tugas dalam format UUID. Harus sesuai dengan
task_id pada run-task.streamingstringWajibAtur ke
duplex.payloadobjectWajibinputobjectWajibBerisi teks yang akan disintesis.
textstringWajibTeks yang akan disintesis. Maksimal 20.000 karakter per pesan dan 200.000 karakter secara kumulatif.
Interval pengiriman tidak boleh melebihi 23 detik; jika tidak, koneksi akan timeout.
Permintaan:
Respons:
finish-task
Segera setelah semua teks terkirim, klien mengirim finish-task untuk memberi tahu server bahwa input teks selesai dan meminta penyelesaian tugas. Untuk membatalkan giliran sintesis saat ini, atur directive ke cancel dalam input.
headerobjectWajibactionstringWajibJenis perintah. Atur ke
finish-task.task_idstringWajibID tugas dalam format UUID. Harus sesuai dengan
task_id pada run-task.streamingstringWajibAtur ke
duplex.payloadobjectWajibinputobjectWajibAtur ke
{} untuk penyelesaian tugas normal. Sertakan properti directive untuk membatalkan putaran sintesis saat ini.directivestringOpsionalMengontrol 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.- Penyelesaian normal
- Batalkan tugas
Permintaan:
Respons: