Prasyarat
Mulai cepat
Qwen-Audio-TTS
SDK menyediakan antarmuka utama sintesis suara dan mendukung cara pemanggilan berikut:
- Non-streaming: Pemanggilan blocking yang mengirimkan teks lengkap sekaligus dan langsung mengembalikan seluruh audio. Cocok untuk skenario sintesis suara teks pendek.
- Streaming satu arah: Pemanggilan non-blocking yang mengirimkan teks lengkap sekaligus dan menerima data audio potongan demi potongan melalui iterasi hasil
stream. Cocok untuk skenario sintesis suara teks pendek dengan persyaratan real-time tinggi. - Streaming dua arah: Pemanggilan non-blocking yang dapat mengirim fragmen teks beberapa kali dan menerima aliran audio hasil sintesis inkremental secara real-time melalui iterasi
audio_chunks()/events()sesi. Cocok untuk skenario sintesis suara teks panjang dengan persyaratan real-time tinggi.
- 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.
CosyVoice
SDK menyediakan antarmuka utama sintesis suara, mendukung beberapa cara pemanggilan berikut:
- Panggilan non-streaming: blocking, mengirim teks lengkap sekaligus, langsung mengembalikan audio lengkap. Cocok untuk skenario sintesis suara teks pendek.
- Panggilan streaming satu arah: non-blocking, mengirim teks lengkap sekaligus, menerima data melalui iterasi potongan audio yang dikembalikan
stream. Cocok untuk skenario sintesis suara teks pendek dengan persyaratan real-time tinggi. - Panggilan streaming dua arah: non-blocking, dapat mengirim fragmen teks beberapa kali, menerima aliran audio hasil sintesis inkremental secara real-time melalui iterasi
audio_chunks()/events()milik sesi. Cocok untuk skenario sintesis suara teks panjang dengan persyaratan real-time tinggi.
- Non-streaming
- Streaming satu arah
- Streaming dua arah
Panjang teks yang dikirim dalam satu pemanggilan tidak boleh melebihi 20000 karakter; melebihi batas akan memicu pengecualian
DashScopeError.Parameter permintaan
Qwen-Audio-TTS
Parameter berikut diatur melalui metode synthesize/stream/connect pada client.audio.tts, untuk mengontrol model, voice, format, dan karakteristik audio (model, voice, format, sample_rate, volume, rate, pitch, language_hints, enable_ssml adalah parameter bernama, parameter lainnya diteruskan melalui dictionary parameters).
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
model | str | Ya | Nama model. |
voice | str | Ya | Voice yang digunakan untuk sintesis suara.
|
format | str | Tidak | Mendukung format mp3, wav, pcm, dan lainnya; laju sampel diatur melalui parameter sample_rate, default 22050. |
volume | int | Tidak | Tingkat volume.Nilai default: 50.Nilai valid: [0, 100]. |
rate | float | Tidak | Laju bicara.Nilai default: 1.0.Nilai valid: [0.5, 2.0]. |
pitch | 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].Atur bit_rate melalui dictionary parameters: |
word_timestamp_enabled | bool | Tidak | Menentukan apakah timestamp tingkat kata diaktifkan.Nilai default: false.Hanya tersedia dalam mode keluaran streaming. Suara hasil kloning didukung. Untuk suara sistem yang didukung, lihat Daftar voice Qwen-Audio-TTS.Atur word_timestamp_enabled melalui dictionary parameters: |
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 | Untuk suara multibahasa dan dialek pada qwen-audio-3.1-tts-flash, parameter ini menentukan bahasa atau dialek. Lihat pengaturan suara multibahasa dan dialek untuk detailnya.
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.Atur enable_aigc_tag, aigc_propagator, dan aigc_propagate_id melalui dictionary parameters: |
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.Diatur melalui dictionary parameters. 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.Diatur melalui dictionary parameters. Lihat contoh enable_aigc_tag. |
hot_fix | dict | Tidak | Mengonfigurasi koreksi pelafalan dan penggantian teks yang diterapkan sebelum sintesis.Parameter:
|
CosyVoice
Parameter berikut diatur melalui metode synthesize/stream/connect milik client.audio.tts, digunakan untuk mengontrol model, voice, format, dan karakteristik audio hasil sintesis (model, voice, format, sample_rate, volume, rate, pitch, language_hints, enable_ssml adalah parameter bernama; parameter lainnya diteruskan melalui dictionary parameters).
| 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]. |
rate | float | Tidak | Laju bicara.Nilai default: 1.0.Nilai valid: [0.5, 2.0]. |
pitch | 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: |
Referensi API
Qwen-Audio-TTS
Lihat referensi Qwen-Audio-TTS Python SDK terkini.
Titik akhir layanan
Alamat titik akhir SDK ditentukan oleh parameter konstruktor Client workspace/region (sesuai alamat di bawah, sudah memuat WorkspaceId). Untuk beralih ke wilayah lain, ubah parameter konstruktor Client ke nilai wilayah yang sesuai.
- Singapura
- Tiongkok (Beijing)
- dashscope CLI
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceGanti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.Sumber daya utama (client.audio.tts)
Jalur sumber daya: client.audio.tts
Fungsi: Sintesis suara berbasis WebSocket, menyediakan tiga bentuk pemanggilan: sintesis sekali jalan (synthesize), sintesis streaming (stream), dan sesi streaming dua arah (connect).
Titik masuk pemanggilan
synthesize() - 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 non-streaming, memblokir dan mengembalikan seluruh data audio sekaligus. Cocok untuk teks pendek tanpa persyaratan real-time yang ketat. synthesize dan stream membuat sesinya sendiri pada setiap pemanggilan, tidak perlu menggunakan ulang instans.
stream() - 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. |
Iterator[bytes], data audio yang dihasilkan potongan demi potongan.
Deskripsi: Sintesis streaming, mengirim teks lengkap sekaligus dan menghasilkan audio potongan demi potongan (Iterator[bytes]). Cocok untuk skenario sintesis suara teks pendek dengan persyaratan real-time tinggi. Jika perlu mengirim teks per fragmen, gunakan sesi streaming dua arah (connect).
send_text() - input streaming (metode sesi)
Mengirim teks per fragmen dalam sesi streaming dua arah (client.audio.tts.connect(...)).
Signature metode:
text adalah fragmen teks yang akan disintesis saat ini. send_text dapat dipanggil beberapa kali untuk menambahkan teks, maksimum 20.000 karakter per panggilan dan 200.000 karakter secara kumulatif. Pengiriman teks dan penerimaan audio harus berjalan secara bersamaan (dikombinasikan dengan audio_chunks()/events() dan stop).
stop() - akhiri input streaming (metode sesi)
Signature metode:audio_chunks()/events() hingga teks yang tersisa selesai disintesis dan seluruh data audio dikembalikan. Tidak memanggil metode ini dapat menyebabkan teks di bagian akhir tidak dikonversi menjadi suara.
cancel() - batalkan sintesis streaming (metode sesi)
Signature metode:Metrik sesi dan respons (atribut sesi)
first_package_delay:float, latensi dari pengiriman teks hingga diterimanya potongan data audio pertama (dalam milidetik). Dibaca setelah sintesis selesai.usage:dict, informasi penggunaan dari tugas sintesis terbaru.last_response:dict, pesan respons dari tugas sintesis terbaru (memuat kunciheader/payload). request_id dari permintaan terbaru dapat diambil dariheaderpadasession.last_response, berguna untuk pemecahan masalah dan korelasi log.
Sesi dan iterasi event
Sintesis streaming tidak lagi menggunakan antarmuka callback: audio dan event server diterima melalui metode iterasi sesi. stream()/synthesize() tidak memerlukan pengelolaan sesi; siklus hidup sesi streaming dua arah (client.audio.tts.connect(...)): memasuki konteks with otomatis membentuk koneksi → beberapa kali send_text() → stop() → membaca seluruh hasil → keluar dari konteks otomatis menutup koneksi.
audio_chunks() - iterasi data audio
Signature metode:Iterator[bytes], fragmen data biner audio yang dihasilkan potongan demi potongan, formatnya ditentukan oleh parameter format.
Deskripsi: Diiterasi di thread penerima, menerima data audio potongan demi potongan; selama proses sintesis akan dihasilkan beberapa potongan. Data dapat ditulis ke file atau dikirim ke perangkat pemutaran. Satu sesi hanya mengizinkan satu pembaca events() atau audio_chunks().
events() - iterasi event server
Signature metode:dict, memuat header (informasi permintaan) dan payload (informasi output)) maupun audio bytes. payload.output memuat tipe event, teks asli, dan informasi lainnya; untuk detailnya lihat bidang output dalam event events().
Deskripsi: Iterasi balasan server di thread penerima, memuat informasi output event sintesis (tipe event, teks asli, informasi kalimat, dsb.); akses payload.output secara langsung untuk mendapatkan informasi detail.
Penanganan error
Saat terjadi error selama proses sintesis, lapisan ws akan melemparkan pengecualianDashScopeError, dan koneksi akan ditutup otomatis setelah pengecualian dipicu. Anda dapat menangkapnya dengan try/except di sisi pengiriman/penerimaan dan mencatat log error untuk memudahkan pemecahan masalah:
Siklus hidup sesi
- Memasuki konteks
withotomatis membentuk koneksi (sebelum itu Anda dapat menginisialisasi aliran output audio atau membuka file dan sumber daya lainnya). - Setelah seluruh teks selesai disintesis dan seluruh data audio telah dihasilkan, iterasi
events()/audio_chunks()berakhir; setelah itu metrik performa sepertifirst_package_delaydapat dibaca. - Keluar dari konteks
withotomatis menutup koneksi (setelah itu Anda dapat melepas sumber daya seperti perangkat pemutaran audio).
Bidang output dalam event events()
Event dict yang dihasilkan dari iterasi events() sesi memuat payload.output dengan informasi output event sintesis, yang dapat digunakan untuk melacak progres sintesis dan mendapatkan informasi per kalimat. Berikut adalah penjelasan struktur bidang output:
| 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). |
CosyVoice
Lihat referensi CosyVoice Python SDK terkini.
Titik akhir layanan
Titik akhir SDK ditentukan oleh parameter konstruksi workspace/region milik Client (sesuai alamat di bawah, memuat WorkspaceId). Untuk beralih ke wilayah lain, ubah parameter konstruksi Client menjadi nilai wilayah yang sesuai.
- Singapura
- Tiongkok (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceGanti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.Sumber daya inti (client.audio.tts)
Jalur resource: client.audio.tts
Fungsi: Sintesis suara berbasis WebSocket, menyediakan tiga bentuk pemanggilan: sintesis sekali jalan (synthesize), sintesis streaming (stream), dan sesi streaming dua arah (connect).
Titik masuk pemanggilan
synthesize() - non-streaming
Signature metode:| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
text | str | Ya | Teks lengkap yang akan disintesis. Panjang maksimum: 20.000 karakter. |
bytes, data audio lengkap.
Deskripsi: Panggilan non-streaming, memblokir dan mengembalikan seluruh data audio sekaligus. Cocok untuk teks pendek tanpa persyaratan real-time yang ketat. synthesize dan stream membuat sesinya sendiri pada setiap pemanggilan, tidak perlu menggunakan kembali instans.
stream() - panggilan 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. |
Iterator[bytes], data audio yang dihasilkan potongan demi potongan.
Deskripsi: Sintesis streaming, mengirim teks lengkap sekaligus dan menghasilkan audio potongan demi potongan (Iterator[bytes]). Cocok untuk skenario sintesis suara teks pendek dengan persyaratan real-time tinggi. Jika perlu mengirim teks secara bertahap, gunakan sesi streaming dua arah (connect).
send_text() - input streaming (metode sesi)
Mengirim teks secara bertahap dalam sesi streaming dua arah (client.audio.tts.connect(...)).
Signature metode:
text adalah fragmen teks yang akan disintesis saat ini. send_text dapat dipanggil beberapa kali untuk menambahkan teks, maksimal 20000 karakter per pemanggilan dan maksimal 200000 karakter kumulatif. Pengiriman teks dan penerimaan audio harus berjalan konkuren (gunakan bersama audio_chunks()/events() dan stop).
stop() - akhiri input streaming (metode sesi)
Signature metode:audio_chunks()/events() hingga sintesis teks yang tersisa selesai dan seluruh data audio dikembalikan. Tidak memanggil metode ini dapat menyebabkan teks di bagian akhir gagal dikonversi menjadi suara.
cancel() - batalkan sintesis streaming (metode sesi)
Signature metode:Metrik sesi dan respons (atribut sesi)
first_package_delay:float, waktu tunda (milidetik) dari pengiriman teks hingga diterimanya blok data audio pertama. Perlu dibaca setelah sintesis selesai.usage:dict, informasi penggunaan dari tugas sintesis terbaru.last_response:dict, pesan respons dari tugas sintesis terbaru (memuat kunciheader/payload). request_id permintaan terakhir dapat diperoleh dariheaderpadasession.last_response, berguna untuk pemecahan masalah dan korelasi log.
Iterasi sesi dan event
Sintesis streaming tidak lagi menggunakan antarmuka callback: audio dan event server diterima melalui metode iterasi milik sesi. stream()/synthesize() tidak memerlukan pengelolaan sesi; siklus hidup sesi streaming dua arah (client.audio.tts.connect(...)) adalah: masuki konteks with untuk membuat koneksi secara otomatis → beberapa kali send_text() → stop() → baca seluruh hasil → keluar dari konteks untuk menutup koneksi secara otomatis.
audio_chunks() - iterasi data audio
Signature metode:Iterator[bytes], fragmen data biner audio yang dihasilkan potongan demi potongan, formatnya ditentukan oleh parameter format.
Deskripsi: Diiterasi pada thread penerima, menerima data audio potongan demi potongan; selama proses sintesis banyak potongan akan dihasilkan. Data dapat ditulis ke file atau dikirim ke perangkat pemutaran. Satu sesi hanya mengizinkan satu pembaca events() atau audio_chunks().
events() - iterasi event server
Signature metode:dict, memuat header (informasi permintaan) dan payload (informasi output)) dan bytes audio. payload.output di dalamnya memuat tipe event, teks asli, dan informasi lainnya; lihat bidang output dalam event events().
Deskripsi: Mengiterasi balasan server pada thread penerima, memuat informasi output event sintesis (tipe event, teks asli, informasi kalimat, dll.); dapat langsung mengakses payload.output untuk detailnya.
Penanganan error
Saat terjadi error selama proses sintesis, lapisan ws akan melemparkannya sebagai pengecualianDashScopeError; setelah pengecualian terpicu, koneksi akan ditutup secara otomatis. Anda dapat menangkapnya dengan try/except di sisi pengirim/penerima dan mencatat log error untuk memudahkan investigasi masalah:
Siklus hidup sesi
- Koneksi dibuat otomatis saat memasuki konteks
with(sebelum itu Anda dapat menginisialisasi aliran output audio atau membuka sumber daya seperti file). - Setelah semua teks selesai disintesis dan seluruh data audio telah dihasilkan, iterasi
events()/audio_chunks()berakhir; setelahnya metrik performa sepertifirst_package_delaydapat dibaca. - Koneksi ditutup otomatis saat keluar dari konteks
with(setelahnya Anda dapat melepas sumber daya seperti perangkat pemutaran audio).
Bidang output dalam event events()
Dalam event dict yang dihasilkan oleh iterasi events() milik sesi, payload.output memuat informasi output event sintesis, dapat digunakan untuk melacak progres sintesis dan mendapatkan informasi per kalimat. Berikut penjelasan struktur bidang output:
| 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). |