Skip to main content

Qwen-Audio-TTS / CosyVoice Python SDK

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.
synthesize dan stream membuat sesinya sendiri pada setiap pemanggilan, tidak perlu menggunakan ulang instans.
# coding=utf-8

import os

import dashscope

# Kunci API wilayah Singapura berbeda dengan wilayah Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
# Jika variabel lingkungan tidak dikonfigurasi, atur Kunci API Anda secara langsung: api_key="sk-xxx"
# Berikut adalah konfigurasi untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Model
model = "qwen-audio-3.0-tts-flash"
# Voice
voice = "longanhuan_v3.6"

# Kirim teks yang akan disintesis dan dapatkan audio biner
audio = client.audio.tts.synthesize("How is the weather today?", model=model, voice=voice)

# Simpan audio ke file lokal
with open('output.mp3', 'wb') as f:
    f.write(audio)

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.
synthesize dan stream membuat sesinya sendiri pada setiap pemanggilan, tidak perlu menggunakan kembali instans.
# coding=utf-8

import os

import dashscope

# Kunci API wilayah Singapura berbeda dengan wilayah Beijing. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Jika variabel lingkungan tidak dikonfigurasi, atur API Key Anda secara langsung: api_key = "sk-xxx"
# Konfigurasi berikut untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja Anda yang sebenarnya. Nilai region berbeda-beda untuk setiap wilayah.
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Model
model = "cosyvoice-v3-plus"
# Voice
voice = "longanyang"

# Kirim teks untuk disintesis dan dapatkan audio biner
audio = client.audio.tts.synthesize("How is the weather today?", model=model, voice=voice)

# Simpan audio ke file lokal
with open('output.mp3', 'wb') as f:
    f.write(audio)

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).
ParameterTipeWajibDeskripsi
modelstrYaNama model.
voicestrYaVoice yang digunakan untuk sintesis suara.
  • Voice sistem: Lihat Daftar voice Qwen-Audio-TTS
  • Suara kloning: Suara kustom yang dibuat melalui kloning suara.
  • Suara kustom: Suara yang dibuat melalui desain suara.
formatstrTidakMendukung format mp3, wav, pcm, dan lainnya; laju sampel diatur melalui parameter sample_rate, default 22050.
volumeintTidakTingkat volume.Nilai default: 50.Nilai valid: [0, 100].
ratefloatTidakLaju bicara.Nilai default: 1.0.Nilai valid: [0.5, 2.0].
pitchfloatTidakPitch.Nilai default: 1.0.Nilai valid: [0.5, 2.0].
bit_rateintTidakBit 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:
audio = client.audio.tts.synthesize(
    "Teks yang akan disintesis",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    parameters={"bit_rate": 128},
)
word_timestamp_enabledboolTidakMenentukan 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:
audio = client.audio.tts.stream(
    "Teks yang akan disintesis",
    model="qwen-audio-3.0-tts-flash",
    voice="your_voice",  # Voice sistem atau hasil kloning yang mendukung timestamp tingkat kata
    parameters={"word_timestamp_enabled": True},
)
seedintTidakSeed 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_hintslist[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.
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:
  • 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
  • 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
  • other: Bahasa lain (didukung oleh qwen-audio-3.1-tts-flash) Bulgaria, Belanda, Hungaria, Rumania, Denmark, Kroasia, Yunani, Ceko, Norwegia, Swedia, Hindi, Slovak, Finlandia, Urdu, Serbia, Spanyol (Meksiko), Lituania, Latvia, Turki, Persia, Ibrani, Mongolia, Slovenia, Azerbaijan, Polandia, Katalan, Khmer, Portugis (Brasil), Lao, Georgia, Afrikaans, Nepali, Belarusia, Malayalam, Luksemburg, Albania, Tamil, Sinhala, Telugu, Estonia, Cebuano, Bosnia, Burma, Armenia, Latin, Islandia, Malta, Swahili, Kazakh, Seselwa Kreol Prancis, Ukraina.
  • Parameter ini berupa array, tetapi versi saat ini hanya memproses elemen pertama. Berikan satu nilai saja.
  • Parameter ini menentukan bahasa target untuk sintesis suara. Parameter ini tidak terkait dengan bahasa sampel audio yang digunakan dalam kloning suara. Untuk mengatur bahasa sumber dalam tugas kloning, lihat referensi API kloning suara.
instructionstrTidakMengontrol karakteristik sintesis seperti dialek, emosi, atau gaya berbicara.Untuk detail penggunaan, lihat Kontrol instruksi.
enable_aigc_tagboolTidakMenentukan 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:
audio = client.audio.tts.synthesize(
    "Teks yang akan disintesis",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    parameters={
        "enable_aigc_tag": True,
        "aigc_propagator": "your_propagator",
        "aigc_propagate_id": "your_propagate_id"
    },
)
aigc_propagatorstrTidakMengatur 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_idstrTidakMengatur 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_fixdictTidakMengonfigurasi koreksi pelafalan dan penggantian teks yang diterapkan sebelum sintesis.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 aktual.
Contoh:
audio = client.audio.tts.synthesize(
    "Teks yang akan disintesis",
    model="qwen-audio-3.0-tts-flash",
    voice="your_voice_id", # Voice
    parameters={
        "hot_fix": {
            "pronunciation": [{"天气": "tian1 qi4"}],
            "replace": [{"今天": "金天"}]
        }
    },
)

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).
ParameterTipeWajibDeskripsi
modelstrYaNama model.
voicestrYaVoice yang digunakan untuk sintesis suara.
  • Voice sistem: Lihat Daftar Voice CosyVoice
  • Suara kloning: Suara kustom yang dibuat melalui kloning suara.
  • Suara kustom: Suara yang dibuat melalui desain suara.
formatenumTidakFormat 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.
volumeintTidakTingkat volume.Nilai default: 50.Nilai valid: [0, 100].
ratefloatTidakLaju bicara.Nilai default: 1.0.Nilai valid: [0.5, 2.0].
pitchfloatTidakPitch.Nilai default: 1.0.Nilai valid: [0.5, 2.0].
bit_rateintTidakBit 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:
audio = client.audio.tts.synthesize(
    "Teks yang akan disintesis",
    model="cosyvoice-v3-plus",
    voice="longanyang",
    parameters={"bit_rate": 128},
)
word_timestamp_enabledboolTidakMenentukan 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:
audio = client.audio.tts.stream(
    "Teks yang akan disintesis",
    model="cosyvoice-v3-flash",
    voice="your_voice",  # Voice sistem atau hasil kloning yang mendukung timestamp tingkat kata
    parameters={"word_timestamp_enabled": True},
)
seedintTidakSeed 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_hintslist[str]Tidak
  • Parameter ini berupa array, tetapi versi saat ini hanya memproses elemen pertama. Berikan satu nilai saja.
  • Parameter ini menentukan bahasa target untuk sintesis suara. Parameter ini tidak terkait dengan bahasa sampel audio yang digunakan dalam kloning suara. Untuk mengatur bahasa sumber dalam tugas kloning, lihat referensi API kloning suara.
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:
  • 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
  • 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
instructionstrTidakMengontrol karakteristik sintesis seperti dialek, emosi, atau gaya berbicara.Untuk detail penggunaan, lihat Kontrol instruksi.
enable_aigc_tagboolTidakMenentukan 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.
Setel enable_aigc_tag, aigc_propagator, dan aigc_propagate_id melalui parameter additional_params:
audio = client.audio.tts.synthesize(
    "Teks yang akan disintesis",
    model="cosyvoice-v3-plus",
    voice="longanyang",
    parameters={
        "enable_aigc_tag": True,
        "aigc_propagator": "your_propagator",
        "aigc_propagate_id": "your_propagate_id"
    },
)
aigc_propagatorstrTidakMengatur 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.
Diatur melalui parameter additional_params. Lihat contoh enable_aigc_tag.
aigc_propagate_idstrTidakMengatur 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.
Diatur melalui parameter additional_params. Lihat contoh enable_aigc_tag.
hot_fixdictTidakMengonfigurasi koreksi pelafalan dan penggantian teks yang diterapkan sebelum sintesis.
Fitur 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 aktual.
Contoh:
audio = client.audio.tts.synthesize(
    "Teks yang akan disintesis",
    model="cosyvoice-v3-plus",
    voice="longanyang", # Voice
    parameters={
        "hot_fix": {
            "pronunciation": [{"天气": "tian1 qi4"}],
            "replace": [{"今天": "金天"}]
        }
    },
)
enable_markdown_filterboolTidak
Hanya voice hasil kloning 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 dibacakan.Nilai default: false.Nilai valid:
  • true: Aktifkan penyaringan Markdown
  • false: Nonaktifkan penyaringan Markdown
Setel enable_markdown_filter melalui parameter additional_params:
audio = client.audio.tts.synthesize(
    "Teks yang akan disintesis",
    model="cosyvoice-v3-flash",
    voice="your_voice",  # Voice hasil kloning dari cosyvoice-v3-flash
    parameters={"enable_markdown_filter": True},
)

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.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah Tiongkok (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru:
  • Tiongkok (Beijing): dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

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
# Sintesis sekali jalan: mengembalikan seluruh byte audio
audio = client.audio.tts.synthesize(
    text,                      # text wajib (argumen posisi)
    model="qwen-audio-3.0-tts-flash", # Model tempat voice tersebut berada
    voice="longanhuan_v3.6",   # Voice
    format="mp3",              # Format enkode audio, default "mp3"
    sample_rate=22050,         # Laju sampel, default 22050
)

# Sintesis streaming: menghasilkan byte audio potongan demi potongan (tulis/putar sambil menerima)
for chunk in client.audio.tts.stream(text, model=..., voice=...):
    ...

# Sesi streaming dua arah: kirim teks per segmen; koneksi otomatis terbentuk saat memasuki konteks with
with client.audio.tts.connect(model=..., voice=...) as session:
    session.send_text(text)    # Dapat dipanggil beberapa kali untuk menambahkan teks
    session.stop()             # Memberi tahu server bahwa input telah selesai
    for chunk in session.audio_chunks():
        ...
synthesize() - non-streaming
Signature metode:
def synthesize(self, text: str, *, model: str,
               voice: str, format: str = "mp3",
               sample_rate: int = 22050, volume: int = None,
               rate: float = None, pitch: float = None,
               language_hints: list = None, enable_ssml: bool = None,
               parameters: Dict = None, ...) -> bytes
Parameter:
ParameterTipeWajibDeskripsi
textstrYaTeks lengkap yang akan disintesis. Panjang maksimum: 20.000 karakter.
Nilai kembalian: 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:
def stream(self, text: str, *, model: str, voice: str,
           format: str = "mp3", sample_rate: int = 22050, ...) -> Iterator[bytes]
Parameter:
ParameterTipeWajibDeskripsi
textstrYaSegmen teks yang akan disintesis. Panggil metode ini beberapa kali untuk menambahkan teks. Maksimum per pemanggilan: 20.000 karakter. Maksimum kumulatif: 200.000 karakter.
Nilai kembalian: 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:
def send_text(self, text: str) -> None
Deskripsi parameter: 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:
def stop(self) -> None
Deskripsi: Memberi tahu server bahwa seluruh teks telah dikirim. Setelah dipanggil, metode ini tidak memblokir thread saat ini; thread penerima harus terus mengonsumsi 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:
def cancel(self) -> None
Deskripsi: Membatalkan tugas sintesis suara streaming pada giliran saat ini. Setelah dipanggil, SDK segera mengakhiri tugas saat ini. Setelah pembatalan, sesi saat ini tidak dapat lagi mengirim teks; untuk melanjutkan sintesis, buat sesi baru.
Metrik sesi dan respons (atribut sesi)
session.first_package_delay
session.usage
session.last_response
  • 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 kunci header/payload). request_id dari permintaan terbaru dapat diambil dari header pada session.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:
def audio_chunks(self) -> Iterator[bytes]
Nilai kembalian: 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:
def events(self) -> Generator[Union[Dict, bytes], None, None]
Nilai kembalian: Menghasilkan baik event respons server (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 pengecualian DashScopeError, 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:
from dashscope import DashScopeError

try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
Siklus hidup sesi
  • Memasuki konteks with otomatis 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 seperti first_package_delay dapat dibaca.
  • Keluar dari konteks with otomatis 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:
BidangTipeDeskripsi
typestrTipe event. Nilai: sentence-begin (sintesis kalimat dimulai), sentence-synthesis (sintesis kalimat sedang berlangsung), atau sentence-end (sintesis kalimat selesai).
original_textstrTeks asli dari kalimat saat ini. Dikembalikan dalam event sentence-begin dan sentence-end.
sentencedictInformasi kalimat. Berisi index (nomor urut kalimat) dan words (daftar kata dengan informasi timestamp saat word_timestamp_enabled aktif).
Contoh pesan:
{
  "header": {
    "task_id": "xxx",
    "event": "result-generated",
    "attributes": {}
  },
  "payload": {
    "output": {
      "type": "sentence-begin",
      "original_text": "How is the weather today?",
      "sentence": {
        "index": 0,
        "words": []
      }
    }
  }
}
Contoh penguraian:
def handle_event(event):
    output = (event.get('payload') or {}).get('output') or {}
    event_type = output.get('type', '')
    original_text = output.get('original_text', '')
    if event_type:
        print(f'Tipe event: {event_type}, Teks asli: {original_text}')

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.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah Tiongkok (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru:
  • Tiongkok (Beijing): dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

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
# Sintesis sekali jalan: mengembalikan seluruh bytes audio
audio = client.audio.tts.synthesize(
    text,                      # teks wajib (argumen posisi)
    model="cosyvoice-v3-plus", # Model tempat voice tersebut berada
    voice="longanyang",        # Voice
    format="mp3",              # Format encoding audio, default "mp3"
    sample_rate=22050,         # Laju sampel, default 22050
)

# Sintesis streaming: menghasilkan bytes audio potongan demi potongan (tulis/putar sambil menerima)
for chunk in client.audio.tts.stream(text, model=..., voice=...):
    ...

# Sesi streaming dua arah: kirim teks secara bertahap; koneksi dibuat otomatis saat memasuki konteks with
with client.audio.tts.connect(model=..., voice=...) as session:
    session.send_text(text)    # Dapat dipanggil beberapa kali untuk menambahkan teks
    session.stop()             # Memberi tahu server bahwa input telah selesai
    for chunk in session.audio_chunks():
        ...
synthesize() - non-streaming
Signature metode:
def synthesize(self, text: str, *, model: str = "cosyvoice-v1",
               voice: str = "longxiaochun", format: str = "mp3",
               sample_rate: int = 22050, volume: int = None,
               rate: float = None, pitch: float = None,
               language_hints: list = None, enable_ssml: bool = None,
               parameters: Dict = None, ...) -> bytes
Deskripsi parameter:
ParameterTipeWajibDeskripsi
textstrYaTeks lengkap yang akan disintesis. Panjang maksimum: 20.000 karakter.
Nilai kembalian: 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:
def stream(self, text: str, *, model: str, voice: str,
           format: str = "mp3", sample_rate: int = 22050, ...) -> Iterator[bytes]
Deskripsi parameter:
ParameterTipeWajibDeskripsi
textstrYaSegmen teks yang akan disintesis. Panggil metode ini beberapa kali untuk menambahkan teks. Maksimum per pemanggilan: 20.000 karakter. Maksimum kumulatif: 200.000 karakter.
Nilai kembalian: 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:
def send_text(self, text: str) -> None
Deskripsi parameter: 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:
def stop(self) -> None
Deskripsi: Memberi tahu server bahwa semua teks telah selesai dikirim. Setelah dipanggil, metode ini tidak memblokir thread saat ini; thread penerima perlu terus mengonsumsi 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:
def cancel(self) -> None
Deskripsi: Membatalkan tugas sintesis suara streaming pada giliran saat ini. Setelah dipanggil, SDK akan segera mengakhiri tugas saat ini. Setelah dibatalkan, sesi saat ini tidak dapat lagi mengirim teks; untuk melanjutkan sintesis, buat sesi baru.
Batasan model:
  • Wilayah Tiongkok (Beijing): hanya CosyVoice v2 dan yang lebih baru yang mendukung fitur ini.
  • Wilayah Singapura: model seri CosyVoice tidak mendukung fitur ini.
Metrik sesi dan respons (atribut sesi)
session.first_package_delay
session.usage
session.last_response
  • 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 kunci header/payload). request_id permintaan terakhir dapat diperoleh dari header pada session.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:
def audio_chunks(self) -> Iterator[bytes]
Nilai kembalian: 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:
def events(self) -> Generator[Union[Dict, bytes], None, None]
Nilai kembalian: Menghasilkan sekaligus event respons server (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 pengecualian DashScopeError; 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:
from dashscope import DashScopeError

try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
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 seperti first_package_delay dapat 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:
BidangTipeDeskripsi
typestrTipe event. Nilai: sentence-begin (sintesis kalimat dimulai), sentence-synthesis (sintesis kalimat sedang berlangsung), atau sentence-end (sintesis kalimat selesai).
original_textstrTeks asli dari kalimat saat ini. Dikembalikan dalam event sentence-begin dan sentence-end.
sentencedictInformasi kalimat. Berisi index (nomor urut kalimat) dan words (daftar kata dengan informasi timestamp saat word_timestamp_enabled aktif).
Contoh pesan:
{
  "header": {
    "task_id": "xxx",
    "event": "result-generated",
    "attributes": {}
  },
  "payload": {
    "output": {
      "type": "sentence-begin",
      "original_text": "How is the weather today?",
      "sentence": {
        "index": 0,
        "words": []
      }
    }
  }
}
Contoh penguraian:
def handle_event(event):
    output = (event.get('payload') or {}).get('output') or {}
    event_type = output.get('type', '')
    original_text = output.get('original_text', '')
    if event_type:
        print(f'Tipe event: {event_type}, Teks asli: {original_text}')