Gunakan DashScope Python SDK untuk mengintegrasikan sintesis suara real-time CosyVoice ke dalam aplikasi Anda melalui mode non-streaming, streaming satu arah, atau streaming dua arah.
Titik akhir layanan
SDK menggunakan titik akhir Wilayah Beijing secara default. Untuk beralih ke wilayah lain, ubah dashscope.base_websocket_api_url sebelum inisialisasi.
- Singapura
- Tiongkok (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceGanti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.SpeechSynthesizer
Jalur paket: dashscope.audio.tts_v2.SpeechSynthesizer
Konstruktor
call() - non-streaming
Signature metode:
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
text | str | Ya | Teks lengkap yang akan disintesis. Panjang maksimum: 20.000 karakter. |
bytes yang berisi data audio lengkap.
Deskripsi: Pemanggilan blocking ini mengembalikan seluruh data audio sekaligus. Metode ini paling cocok untuk teks pendek yang tidak memerlukan streaming real-time. Inisialisasi ulang instans SpeechSynthesizer sebelum setiap pemanggilan.
streaming_call() - streaming
Signature metode:
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
text | str | Ya | Segmen teks yang akan disintesis. Panggil metode ini beberapa kali untuk menambahkan teks. Maksimum per pemanggilan: 20.000 karakter. Maksimum kumulatif: 200.000 karakter. |
streaming_complete() - akhiri streaming
Signature metode:
streaming_cancel() - batalkan sintesis streaming
Signature metode:
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
complete_timeout_millis | int | Tidak | Timeout dalam milidetik untuk menunggu server mengembalikan event task-finished. Nilai default: 10000. |
SpeechSynthesizer.
get_last_request_id() - dapatkan ID permintaan
Signature metode:
str yang berisi ID permintaan dari permintaan terbaru. Gunakan ini untuk troubleshooting dan pelacakan.
get_first_package_delay() - dapatkan latensi paket pertama
Signature metode:
int yang merepresentasikan delay dalam milidetik dari pengiriman teks hingga menerima chunk audio pertama. Panggil ini setelah sintesis selesai.
get_response() - dapatkan pesan respons
Signature metode:
str yang berisi pesan respons dalam format JSON dari tugas sintesis terbaru, termasuk status permintaan dan informasi output.
Parameter konstruktor
Parameter berikut ditetapkan melalui konstruktor SpeechSynthesizer untuk mengontrol model, voice, format, dan karakteristik audio.
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
model | str | Ya | Nama model. |
voice | str | Ya | Voice yang digunakan untuk sintesis suara.
|
format | enum | Tidak | Format encoding audio dan laju sampel.Default: AudioFormat.MP3_22050HZ_MONO_256KBPS.Enum AudioFormat terletak di dashscope.audio.tts_v2 dan mendukung format MP3, WAV, PCM, dan lainnya. |
volume | int | Tidak | Tingkat volume.Nilai default: 50.Nilai valid: [0, 100]. |
speech_rate | float | Tidak | Laju bicara.Nilai default: 1.0.Nilai valid: [0.5, 2.0]. |
pitch_rate | float | Tidak | Pitch.Nilai default: 1.0.Nilai valid: [0.5, 2.0]. |
bit_rate | int | Tidak | Bit rate audio dalam kbps. Saat format audio adalah mp3 atau opus, gunakan bit_rate untuk menyesuaikan bit rate.Nilai default: 32.Nilai valid: [6, 510].Setel bit_rate melalui parameter additional_params: |
word_timestamp_enabled | bool | Tidak | Menentukan apakah timestamp tingkat kata diaktifkan.Nilai default: false.Hanya tersedia dalam mode keluaran streaming. Voice yang didukung: voice hasil kloning dari cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2, serta voice sistem yang ditandai sebagai didukung di Daftar Voice CosyVoice. Voice hasil kloning dari model lain tidak mendukung fitur ini.Setel word_timestamp_enabled melalui parameter additional_params: |
seed | int | Tidak | Seed acak untuk mengontrol variasi dalam output sintesis. Ketika versi model, teks, voice, dan parameter lainnya tidak berubah, menggunakan seed yang sama menghasilkan output identik.Nilai default: 0.Nilai valid: [0, 65535]. |
language_hints | list[str] | Tidak | Menentukan bahasa target untuk sintesis suara guna meningkatkan kualitas output.Saat pelafalan angka, ekspansi singkatan, pembacaan simbol, atau sintesis bahasa minoritas tidak sesuai ekspektasi, gunakan parameter ini. Contohnya:
Nilai yang valid
|
instruction | str | Tidak | Mengontrol karakteristik sintesis seperti dialek, emosi, atau gaya berbicara.Untuk detail penggunaan, lihat Kontrol instruksi. |
enable_aigc_tag | bool | Tidak | Menentukan apakah watermark AIGC disematkan dalam audio yang dihasilkan. Saat diatur ke true, watermark disematkan dalam 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. enable_aigc_tag, aigc_propagator, dan aigc_propagate_id melalui parameter additional_params: |
aigc_propagator | str | Tidak | Mengatur 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. additional_params. Lihat contoh enable_aigc_tag. |
aigc_propagate_id | str | Tidak | 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 cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 yang mendukung fitur ini. additional_params. Lihat contoh enable_aigc_tag. |
hot_fix | dict | Tidak | Mengonfigurasi koreksi pelafalan dan penggantian teks yang diterapkan sebelum sintesis. Fitur ini tidak didukung oleh cosyvoice-v2.
|
enable_markdown_filter | bool | Tidak | Hanya voice hasil kloning dari cosyvoice-v3-flash yang mendukung fitur ini.
enable_markdown_filter melalui parameter additional_params: |
callback | ResultCallback | Tidak | Instans callback untuk menerima audio hasil sintesis dan notifikasi event secara asinkron. Saat diatur, call() berjalan dalam mode streaming dan mengirimkan audio melalui callback on_data. Saat tidak diatur, call() berjalan dalam mode non-streaming dan mengembalikan seluruh audio sebagai bytes. |
ResultCallback
Jalur paket: dashscope.audio.tts_v2.ResultCallback
on_open() - koneksi terbentuk
Signature metode:
on_event() - menerima respons server
Signature metode:
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
message | str | Ya | Event respons server dalam format JSON yang berisi header (informasi permintaan) dan payload (informasi output). Bidang payload.output berisi tipe event, teks asli, dan detail lainnya. Lihat bidang output dalam pesan on_event. |
json.loads(message) dan akses payload.output untuk detailnya.
on_complete() - sintesis selesai
Signature metode:
on_data() - menerima data audio
Signature metode:
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
data | bytes | Ya | Chunk data biner audio dalam format yang ditentukan oleh parameter format pada konstruktor. |
on_error() - terjadi error
Signature metode:
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
message | str | Ya | Deskripsi error yang berisi kode kesalahan dan alasan detail. |
on_close() - koneksi ditutup
Signature metode:
Bidang output dalam pesan on_event
Pesan JSON yang diterima oleh callback on_event berisi bidang payload.output dengan informasi event sintesis. Gunakan bidang ini untuk melacak progres sintesis dan mengambil detail per kalimat. Struktur bidang output adalah sebagai berikut:
| Bidang | Tipe | Deskripsi |
|---|---|---|
type | str | Tipe event. Nilai: sentence-begin (sintesis kalimat dimulai), sentence-synthesis (sintesis kalimat sedang berlangsung), atau sentence-end (sintesis kalimat selesai). |
original_text | str | Teks asli dari kalimat saat ini. Dikembalikan dalam event sentence-begin dan sentence-end. |
sentence | dict | Informasi kalimat. Berisi index (nomor urut kalimat) dan words (daftar kata dengan informasi timestamp saat word_timestamp_enabled aktif). |
Contoh kode
SDK mendukung mode sintesis berikut:
- Non-streaming: Pemanggilan blocking yang mengirimkan teks lengkap sekaligus dan mengembalikan seluruh audio langsung. Paling cocok untuk sintesis suara teks pendek.
- Streaming satu arah: Pemanggilan non-blocking yang mengirimkan teks lengkap sekaligus dan mengirimkan data audio (mungkin dalam chunk) melalui fungsi callback. Paling cocok untuk skenario teks pendek yang memerlukan latensi rendah.
- Streaming dua arah: Pemanggilan non-blocking yang mengirimkan teks dalam beberapa segmen dan mengirimkan audio hasil sintesis secara inkremental melalui fungsi callback secara real-time. Paling cocok untuk skenario teks panjang yang memerlukan latensi rendah.
- Non-streaming
- Streaming satu arah
- Streaming dua arah
Teks yang dikirim dalam satu pemanggilan tidak boleh melebihi 20.000 karakter. Melebihi batas ini menyebabkan error.