All Products
Search
Document Center

Alibaba Cloud Model Studio:SDK Python Sintesis Ucapan CosyVoice

Last Updated:Mar 02, 2026

Topik ini menjelaskan parameter dan metode SDK Python untuk sintesis ucapan CosyVoice.

Panduan Pengguna: Untuk pengenalan model dan rekomendasi pemilihan, lihat Sintesis Ucapan Real-time – CosyVoice/Sambert.

Prasyarat

  • Anda telah mengaktifkan Model Studio dan membuat Kunci API. Untuk mencegah risiko keamanan, ekspor Kunci API sebagai variabel lingkungan alih-alih menyematkannya langsung dalam kode Anda.

    Catatan

    Untuk memberikan izin akses sementara kepada aplikasi atau pengguna pihak ketiga, atau jika Anda ingin mengontrol secara ketat operasi berisiko tinggi seperti mengakses atau menghapus data sensitif, kami menyarankan Anda menggunakan token otentikasi sementara.

    Dibandingkan dengan Kunci API jangka panjang, token otentikasi sementara lebih aman karena masa berlakunya singkat (60 detik). Token ini cocok untuk skenario panggilan sementara dan dapat secara efektif mengurangi risiko kebocoran Kunci API.

    Untuk menggunakan token sementara, gantilah Kunci API yang digunakan untuk otentikasi dalam kode Anda dengan token otentikasi sementara tersebut.

  • Instal versi terbaru SDK DashScope.

Model dan harga

Untuk informasi selengkapnya, lihat Sintesis Ucapan Real-time – CosyVoice/Sambert.

Batas teks dan persyaratan format untuk sintesis ucapan

Batas panjang teks

Aturan Perhitungan Karakter

  • Karakter Tionghoa—termasuk Hanzi sederhana, Hanzi tradisional, Kanji Jepang, dan Hanja Korea—dihitung sebagai 2 karakter. Semua karakter lainnya—termasuk tanda baca, huruf, angka, kana Jepang/Hangul Korea—dihitung sebagai 1 karakter.

  • Konten tag SSML tidak termasuk dalam perhitungan panjang teks.

  • Contoh:

    • "你好" → 2 (你) + 2 (好) = 4 karakter

    • "中A文123" → 2 (中) + 1 ('A') + 2 (文) + 1 ('1') + 1 ('2') + 1 ('3') = 8 karakter

    • "Chinese." → 2 (zhong) + 2 (wen) + 1 (titik) = 5 karakter

    • "中 文。" → 2 (中) + 1 (spasi) + 2 (文) + 1 (titik) = 6 karakter

    • "<speak>Hello</speak>" → 2 (ni) + 2 (hao) = 4 karakter

Format Encoding

Gunakan encoding UTF-8.

Dukungan Ekspresi Matematis

Penguraian ekspresi matematis hanya didukung untuk model cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2. Fitur ini mendukung ekspresi matematis umum yang ditemukan di sekolah dasar dan menengah, termasuk namun tidak terbatas pada operasi dasar, aljabar, dan geometri.

Untuk informasi selengkapnya, lihat Formula LaTeX ke ucapan.

Dukungan Speech Synthesis Markup Language (SSML)

Fitur Speech Synthesis Markup Language (SSML) hanya tersedia untuk suara hasil kloning dari model cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2, serta untuk suara sistem yang ditandai sebagai didukung dalam Daftar Suara. Untuk menggunakan fitur ini, penuhi kondisi berikut:

Mulai

Kelas SpeechSynthesizer menyediakan metode inti sintesis ucapan dan mendukung jenis panggilan berikut:

  • Panggilan non-streaming: Blocking. Kirim seluruh teks sekaligus dan terima respons audio lengkap segera. Cocok untuk sintesis ucapan teks pendek.

  • Panggilan streaming satu arah: Non-blocking. Kirim seluruh teks sekaligus dan terima data audio—mungkin tersegmentasi—melalui fungsi callback. Cocok untuk sintesis ucapan teks pendek yang memerlukan performa real-time tinggi.

  • Panggilan streaming dua arah: Non-blocking. Kirim teks dalam beberapa segmen dan terima aliran audio hasil sintesis secara bertahap secara real-time melalui fungsi callback. Cocok untuk sintesis ucapan teks panjang yang memerlukan performa real-time tinggi.

Panggilan non-streaming

Anda dapat mengirimkan satu tugas sintesis ucapan tanpa fungsi callback. Hasil lengkap dikembalikan sekaligus, tanpa keluaran streaming antara.

image

Buat instans kelas SpeechSynthesizer, ikat parameter permintaan, lalu panggil metode call untuk mensintesis dan mengambil data audio biner.

Teks tidak boleh melebihi 20.000 karakter. Untuk informasi selengkapnya, lihat metode call dari kelas SpeechSynthesizer.

Penting

Sebelum setiap pemanggilan metode call, inisialisasi ulang instans SpeechSynthesizer.

Lihat contoh lengkap

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *
import os

# Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Jika Anda belum menyetel variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# URL ini untuk wilayah Singapura. Untuk Beijing, ganti dengan: wss://dashscope.aliyuncs.com/api-ws/v1/inference
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'

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

# Buat instans SpeechSynthesizer dan kirim parameter permintaan seperti model dan voice di konstruktor
synthesizer = SpeechSynthesizer(model=model, voice=voice)
# Kirim teks untuk sintesis dan dapatkan audio biner
audio = synthesizer.call("How is the weather today?")
# Permintaan pertama membuat koneksi WebSocket, sehingga delay paket pertama mencakup waktu pembentukan koneksi
print('[Metric] requestId: {}, first-package delay: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

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

Panggilan streaming satu arah

Anda dapat mengirimkan satu tugas sintesis ucapan dan menerima hasil antara melalui callback. Hasil sintesis dikembalikan melalui fungsi callback ResultCallback.

image

Buat instans kelas SpeechSynthesizer, ikat parameter permintaan dan antarmuka callback (ResultCallback), lalu panggil metode call untuk mensintesis dan menerima hasil secara real-time melalui metode on_data dari antarmuka callback (ResultCallback).

Teks tidak boleh melebihi 20.000 karakter. Untuk informasi selengkapnya, lihat metode call dari kelas SpeechSynthesizer.

Penting

Sebelum setiap pemanggilan metode call, inisialisasi ulang instans SpeechSynthesizer.

Lihat contoh lengkap

# coding=utf-8

import os
import dashscope
from dashscope.audio.tts_v2 import *

from datetime import datetime

def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp

# Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Jika Anda belum menyetel variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# URL ini untuk wilayah Singapura. Untuk Beijing, ganti dengan: wss://dashscope.aliyuncs.com/api-ws/v1/inference
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'

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


# Definisikan antarmuka callback
class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        self.file = open("output.mp3", "wb")
        print("Koneksi terbentuk: " + get_timestamp())

    def on_complete(self):
        print("Sintesis ucapan selesai. Semua hasil diterima: " + get_timestamp())
        # Panggil get_first_package_delay hanya setelah on_complete dipicu
        # Permintaan pertama membuat koneksi WebSocket, sehingga delay paket pertama mencakup waktu pembentukan koneksi
        print('[Metric] requestId: {}, first-package delay: {} ms'.format(
            synthesizer.get_last_request_id(),
            synthesizer.get_first_package_delay()))

    def on_error(self, message: str):
        print(f"Kesalahan sintesis ucapan: {message}")

    def on_close(self):
        print("Koneksi ditutup: " + get_timestamp())
        self.file.close()

    def on_event(self, message):
        pass

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " Panjang audio biner: " + str(len(data)))
        self.file.write(data)


callback = Callback()

# Buat instans SpeechSynthesizer dan kirim parameter permintaan seperti model dan voice di konstruktor
synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    callback=callback,
)

# Kirim teks untuk sintesis dan dapatkan audio biner secara real-time melalui metode on_data dari antarmuka callback
synthesizer.call("How is the weather today?")

Panggilan streaming dua arah

Anda dapat mengirimkan teks secara terfragmentasi dalam satu tugas sintesis ucapan dan menerima hasil secara real-time melalui callback.

Catatan
  • Saat input streaming, Anda dapat memanggil streaming_call beberapa kali untuk mengirimkan fragmen teks secara berurutan. Server secara otomatis membaginya menjadi kalimat.

    • Kalimat lengkap langsung disintesis.

    • Kalimat yang belum lengkap dibuffer hingga lengkap, lalu disintesis.

    Saat Anda memanggil streaming_complete, server memaksa sintesis semua fragmen yang telah diterima tetapi belum diproses, termasuk kalimat yang belum lengkap.

  • Jangan menunggu lebih dari 23 detik antara pengiriman fragmen teks. Jika tidak, kesalahan "request timeout after 23 seconds" akan dikembalikan.

    Jika tidak ada lagi teks yang perlu dikirim, segera panggil metode streaming_complete untuk mengakhiri tugas.

    Server menerapkan timeout tetap 23 detik. Klien tidak dapat mengubah pengaturan ini.
image
  1. Buat instans kelas SpeechSynthesizer

    Buat instans kelas SpeechSynthesizer, dan ikat parameter permintaan dan antarmuka callback (ResultCallback).

  2. Streaming

    Panggil metode streaming_call dari kelas SpeechSynthesizer beberapa kali untuk mengirimkan fragmen teks guna disintesis.

    Saat Anda mengirim teks, server menggunakan metode on_data dari antarmuka callback (ResultCallback) untuk mengembalikan hasil sintesis ke klien secara real-time.

    Setiap pengiriman ke metode streaming_call (parameter text) tidak boleh melebihi 20.000 karakter. Total kumulatif semua pengiriman tidak boleh melebihi 200.000 karakter.

  3. Akhiri pemrosesan

    Panggil metode streaming_complete dari kelas SpeechSynthesizer untuk mengakhiri sintesis ucapan.

    Metode ini memblokir thread saat ini hingga callback on_complete atau on_error dari antarmuka callback (ResultCallback) dipicu.

    Anda harus selalu memanggil metode ini. Jika tidak, teks akhir mungkin tidak dikonversi menjadi ucapan.

Lihat contoh lengkap

# coding=utf-8
#
# Instal PyAudio:
# Di macOS, jalankan:
#   brew install portaudio
#   pip install pyaudio
# Di Debian/Ubuntu, jalankan:
#   sudo apt-get install python-pyaudio python3-pyaudio
#   atau
#   pip install pyaudio
# Di CentOS, jalankan:
#   sudo yum install -y portaudio portaudio-devel && pip install pyaudio
# Di Microsoft Windows, jalankan:
#   python -m pip install pyaudio

import os
import time
import pyaudio
import dashscope
from dashscope.api_entities.dashscope_response import SpeechSynthesisResponse
from dashscope.audio.tts_v2 import *

from datetime import datetime

def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp

# Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Jika Anda belum menyetel variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# URL ini untuk wilayah Singapura. Untuk Beijing, ganti dengan: wss://dashscope.aliyuncs.com/api-ws/v1/inference
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'

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


# Definisikan antarmuka callback
class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        print("Koneksi terbentuk: " + get_timestamp())
        self._player = pyaudio.PyAudio()
        self._stream = self._player.open(
            format=pyaudio.paInt16, channels=1, rate=22050, output=True
        )

    def on_complete(self):
        print("Sintesis ucapan selesai. Semua hasil diterima: " + get_timestamp())

    def on_error(self, message: str):
        print(f"Kesalahan sintesis ucapan: {message}")

    def on_close(self):
        print("Koneksi ditutup: " + get_timestamp())
        # Hentikan pemutar
        self._stream.stop_stream()
        self._stream.close()
        self._player.terminate()

    def on_event(self, message):
        pass

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " Panjang audio biner: " + str(len(data)))
        self._stream.write(data)


callback = Callback()

test_text = [
    "Streaming text-to-speech SDK,",
    "converts input text",
    "into binary audio data.",
    "Compared with non-streaming TTS,",
    "streaming TTS offers better real-time performance.",
    "Users hear near-synchronous audio output",
    "as they type text,",
    "greatly improving interaction and reducing wait time.",
    "Ideal for large language model (LLM) scenarios",
    "where text is streamed for speech synthesis.",
]

# Buat instans SpeechSynthesizer dan kirim parameter permintaan seperti model dan voice di konstruktor
synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    format=AudioFormat.PCM_22050HZ_MONO_16BIT,  
    callback=callback,
)


# Streaming teks untuk sintesis. Dapatkan audio biner secara real-time melalui metode on_data dari antarmuka callback
for text in test_text:
    synthesizer.streaming_call(text)
    time.sleep(0.1)
# Akhiri sintesis ucapan streaming
synthesizer.streaming_complete()

# Permintaan pertama membuat koneksi WebSocket, sehingga delay paket pertama mencakup waktu pembentukan koneksi
print('[Metric] requestId: {}, first-package delay: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

Parameter permintaan

Anda dapat mengatur parameter permintaan di konstruktor kelas SpeechSynthesizer.

Parameter

Tipe

Wajib

Deskripsi

model

str

Ya

model sintesis ucapan.

Versi model yang berbeda memerlukan versi suara yang sesuai:

  • cosyvoice-v3-flash/cosyvoice-v3-plus: Menggunakan suara seperti longanyang.

  • cosyvoice-v2: Menggunakan suara seperti longxiaochun_v2.

  • Untuk daftar lengkap suara, lihat Daftar Suara.

voice

str

Ya

Suara yang digunakan untuk sintesis ucapan.

Mendukung suara sistem dan suara hasil kloning:

  • Suara sistem: Lihat Daftar Suara.

  • Timbre suara hasil kloning: Disesuaikan melalui fitur kloning suara (CosyVoice). Saat menggunakan timbre suara hasil kloning, pastikan kloning suara dan sintesis ucapan menggunakan akun yang sama. Untuk langkah-langkah detail, lihat API kloning suara CosyVoice.

    Saat menggunakan suara hasil kloning, nilai parameter model dari permintaan ini harus persis sama dengan versi model (yaitu parameter target_model) yang digunakan saat membuat suara tersebut.

format

enum

Tidak

Tentukan format encoding audio dan laju sampel.

Jika Anda menghilangkan format, laju sampel default adalah 22,05 kHz dan formatnya MP3.

Catatan

Laju sampel default adalah laju optimal untuk suara yang dipilih. Output menggunakan laju ini secara default tetapi mendukung downsampling atau upsampling.

Format dan laju sampel yang didukung meliputi:

  • Format pengkodean audio dan laju sampel yang didukung untuk semua model:

    • AudioFormat.WAV_8000HZ_MONO_16BIT: Format WAV, laju sampel 8 kHz

    • AudioFormat.WAV_16000HZ_MONO_16BIT: Format WAV, laju sampel 16 kHz

    • AudioFormat.WAV_22050HZ_MONO_16BIT: Format WAV, laju sampel 22,05 kHz

    • AudioFormat.WAV_24000HZ_MONO_16BIT: Format WAV, laju sampel 24 kHz

    • AudioFormat.WAV_44100HZ_MONO_16BIT: Format WAV, laju sampel 44,1 kHz

    • AudioFormat.WAV_48000HZ_MONO_16BIT: Format WAV, laju sampel 48 kHz

    • AudioFormat.MP3_8000HZ_MONO_128KBPS: Format MP3, laju sampel 8 kHz

    • AudioFormat.MP3_16000HZ_MONO_128KBPS: Format MP3, laju sampel 16 kHz

    • AudioFormat.MP3_22050HZ_MONO_256KBPS: Format MP3, laju sampel 22,05 kHz

    • AudioFormat.MP3_24000HZ_MONO_256KBPS: Format MP3, laju sampel 24 kHz

    • AudioFormat.MP3_44100HZ_MONO_256KBPS: Format MP3, laju sampel 44,1 kHz

    • AudioFormat.MP3_48000HZ_MONO_256KBPS: Format MP3, laju sampel 48 kHz

    • AudioFormat.PCM_8000HZ_MONO_16BIT: Format PCM, laju sampel 8 kHz

    • AudioFormat.PCM_16000HZ_MONO_16BIT: Format PCM, laju sampel 16 kHz

    • AudioFormat.PCM_22050HZ_MONO_16BIT: Format PCM, laju sampel 22,05 kHz

    • AudioFormat.PCM_24000HZ_MONO_16BIT: Format PCM, laju sampel 24 kHz

    • AudioFormat.PCM_44100HZ_MONO_16BIT: Format PCM, laju sampel 44,1 kHz

    • AudioFormat.PCM_48000HZ_MONO_16BIT: Format PCM, laju sampel 48 kHz

  • Untuk format OPUS, sesuaikan bitrate menggunakan parameter bit_rate. Tersedia di SDK DashScope 1.24.0 dan lebih baru.

    • AudioFormat.OGG_OPUS_8KHZ_MONO_32KBPS: Format OPUS, laju sampel 8 kHz, bitrate 32 kbps

    • AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS: Format OPUS, laju sampel 16 kHz, bitrate 16 kbps

    • AudioFormat.OGG_OPUS_16KHZ_MONO_32KBPS: Format OPUS, laju sampel 16 kHz, bitrate 32 kbps

    • AudioFormat.OGG_OPUS_16KHZ_MONO_64KBPS: Format OPUS, laju sampel 16 kHz, bitrate 64 kbps

    • AudioFormat.OGG_OPUS_24KHZ_MONO_16KBPS: Format OPUS, laju sampel 24 kHz, bitrate 16 kbps

    • AudioFormat.OGG_OPUS_24KHZ_MONO_32KBPS: Format OPUS, laju sampel 24 kHz, bitrate 32 kbps

    • AudioFormat.OGG_OPUS_24KHZ_MONO_64KBPS: Format OPUS, laju sampel 24 kHz, bitrate 64 kbps

    • AudioFormat.OGG_OPUS_48KHZ_MONO_16KBPS: Format OPUS, laju sampel 48 kHz, bitrate 16 kbps

    • AudioFormat.OGG_OPUS_48KHZ_MONO_32KBPS: Format OPUS, laju sampel 48 kHz, bitrate 32 kbps

    • AudioFormat.OGG_OPUS_48KHZ_MONO_64KBPS: Format OPUS, laju sampel 48 kHz, bitrate 64 kbps

volume

int

Tidak

Volume.

Nilai default: 50.

Rentang: [0, 100]. 50 merepresentasikan volume standar. Volume memiliki hubungan linear dengan nilai ini. 0 adalah senyap, dan 100 adalah volume maksimum.

Penting

Bidang ini berbeda di berbagai versi SDK DashScope:

  • SDK 1.20.10 dan lebih baru: volume

  • SDK sebelum 1.20.10: volumn

speech_rate

float

Tidak

Laju bicara.

Nilai default: 1,0.

Rentang: [0,5, 2,0]. 1,0 adalah laju bicara standar. Nilai kurang dari 1,0 memperlambat bicara, dan nilai lebih dari 1,0 mempercepatnya.

pitch_rate

float

Tidak

Pitch. Nilai ini berfungsi sebagai pengali untuk penyesuaian pitch. Namun, hubungannya dengan perubahan pitch yang dirasakan tidak sepenuhnya linear atau logaritmik. Pilih nilai yang sesuai melalui pengujian.

Nilai default: 1,0.

Rentang: [0,5, 2,0]. 1,0 adalah pitch alami suara. Nilai lebih dari 1,0 meningkatkan pitch, dan nilai kurang dari 1,0 menurunkannya.

bit_rate

int

Tidak

Bitrate audio (dalam kbps). Saat format audio adalah Opus, Anda dapat menyesuaikan bitrate menggunakan parameter bit_rate.

Nilai default: 32.

Rentang: [6, 510].

Catatan

Atur bit_rate menggunakan parameter additional_params:

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longanyang",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"bit_rate": 32})

word_timestamp_enabled

bool

Tidak

Aktifkan timestamp tingkat kata.

Default: False.

  • True: Aktifkan.

  • False: Nonaktifkan.

Fitur ini hanya berfungsi dengan suara hasil kloning untuk cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2, serta dengan suara sistem yang ditandai sebagai mendukung timestamp dalam daftar suara.

Timestamp hanya tersedia melalui antarmuka callback.
Catatan

Atur word_timestamp_enabled menggunakan parameter additional_params:

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longyingjing_v3",
                                callback=callback, # Timestamp hanya tersedia melalui antarmuka callback.
                                additional_params={'word_timestamp_enabled': True})

Lihat kode contoh lengkap

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *
import json
from datetime import datetime


def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp


# Ganti your-api-key dengan Kunci API aktual Anda jika tidak disetel dalam variabel lingkungan.
# dashscope.api_key = "your-api-key"

model = "cosyvoice-v3-flash"
# Voice
voice = "longyingjing_v3"


# Definisikan antarmuka callback
class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        self.file = open("output.mp3", "wb")
        print("Koneksi terbentuk: " + get_timestamp())

    def on_complete(self):
        print("Sintesis ucapan selesai. Semua hasil diterima: " + get_timestamp())

    def on_error(self, message: str):
        print(f"Kesalahan sintesis ucapan: {message}")

    def on_close(self):
        print("Koneksi ditutup: " + get_timestamp())
        self.file.close()

    def on_event(self, message):
        json_data = json.loads(message)
        if json_data['payload'] and json_data['payload']['output'] and json_data['payload']['output']['sentence']:
            sentence = json_data['payload']['output']['sentence']
            print(f'sentence: {sentence}')
            # Dapatkan indeks kalimat
            # index = sentence['index']
            words = sentence['words']
            if words:
                for word in words:
                    print(f'word: {word}')
                    # Contoh: word: {'text': 'T', 'begin_index': 0, 'end_index': 1, 'begin_time': 80, 'end_time': 200}

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " Panjang audio biner: " + str(len(data)))
        self.file.write(data)


callback = Callback()

# Buat instans SpeechSynthesizer dan kirim parameter permintaan seperti model dan voice di konstruktor
synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    callback=callback,
    additional_params={'word_timestamp_enabled': True}
)

# Kirim teks untuk sintesis dan dapatkan audio biner secara real-time melalui metode on_data dari antarmuka callback
synthesizer.call("How is the weather today?")
# Permintaan pertama membuat koneksi WebSocket, sehingga delay paket pertama mencakup waktu pembentukan koneksi
print('[Metric] requestId: {}, first-package delay: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

seed

int

Tidak

Seed bilangan acak yang digunakan selama generasi untuk memvariasikan efek sintesis. Dengan versi model, teks, suara, dan parameter lain yang sama, menggunakan seed yang sama akan menghasilkan hasil sintesis identik.

Nilai default: 0.

Rentang: [0, 65535].

language_hints

list[str]

Tidak

Tentukan bahasa target untuk sintesis ucapan guna meningkatkan kualitas sintesis.

Gunakan ini saat pelafalan angka, singkatan, simbol, atau efek sintesis untuk bahasa minoritas tidak sesuai harapan, seperti:

  • Pelafalan angka yang tidak sesuai: "hello, this is 110" dibaca sebagai "hello, this is one one zero" alih-alih "hello, this is yao yao ling".

  • Pelafalan simbol yang tidak akurat: "@" dibaca sebagai "ait" alih-alih "at".

  • Kualitas sintesis buruk untuk bahasa minoritas, sintesis tidak alami.

Rentang:

  • zh: Tiongkok

  • en: Inggris

  • fr: Prancis

  • de: Jerman

  • ja: Jepang

  • ko: Korea

  • ru: Rusia

Catatan: Parameter ini berupa array, tetapi versi saat ini hanya memproses elemen pertama. Oleh karena itu, kirimkan hanya satu nilai.

Penting

Parameter ini menentukan bahasa target untuk sintesis ucapan. Pengaturan ini tidak terkait dengan bahasa audio sampel yang digunakan dalam kloning suara. Untuk mengatur bahasa sumber untuk tugas kloning, lihat API Kloning Suara CosyVoice.

instruction

str

Tidak

Atur instruksi untuk mengontrol efek sintesis seperti dialek, emosi, atau peran. Fitur ini hanya berlaku untuk suara hasil kloning dari model cosyvoice-v3-flash, serta untuk suara sistem yang mendukung Instruct dalam Daftar Suara.

Batas panjang: 100 karakter.

Karakter Tionghoa (termasuk Hanzi sederhana/tradisional, Kanji Jepang, dan Hanja Korea) dihitung sebagai 2 karakter. Semua karakter lainnya (seperti tanda baca, huruf, angka, kana Jepang/Hangul Korea) dihitung sebagai 1 karakter.

Persyaratan penggunaan (berbeda per model):

  • cosyvoice-v3-flash: Ikuti persyaratan berikut:

    • Suara hasil kloning: Gunakan bahasa alami apa pun untuk mengontrol efek sintesis ucapan.

      Contoh instruksi:

      Please speak in Cantonese. (Supported dialects: Cantonese, Northeast dialect, Gansu dialect, Guizhou dialect, Henan dialect, Hubei dialect, Jiangxi dialect, Minnan dialect, Ningxia dialect, Shanxi dialect, Shaanxi dialect, Shandong dialect, Shanghai dialect, Sichuan dialect, Tianjin dialect, Yunnan dialect.)
      Please speak as loudly as possible.
      Please speak as slowly as possible.
      Please speak as quickly as possible.
      Please speak very softly.
      Can you speak a little slower?
      Can you speak a lot faster?
      Can you speak a lot slower?
      Can you speak a little faster?
      Please speak very angrily.
      Please speak very happily.
      Please speak very fearfully.
      Please speak very sadly.
      Please speak very surprisedly.
      Please try to show a sense of determination.
      Please try to show a feeling of anger.
      Please try a friendly tone.
      Please speak in a cold tone.
      Please speak in a majestic tone.
      I want to experience a natural tone.
      I want to see how you express threat.
      I want to see how you express wisdom.
      I want to see how you express temptation.
      I want to hear you speak in a lively way.
      I want to hear you speak with an impassioned feeling.
      I want to hear you speak in a calm and steady way.
      I want to hear you speak with a confident feeling.
      Can you communicate with me with an excited feeling?
      Can you demonstrate arrogant emotional expression?
      Can you show an elegant emotion?
      Can you answer questions in a happy way?
      Can you give a gentle emotional demonstration?
      Can you talk to me in a calm tone?
      Can you answer me in a profound way?
      Can you talk to me with a rough emotional attitude?
      Tell me this answer in a sinister voice.
      Tell me this answer in a resilient voice.
      Narrate in a natural and friendly conversational style.
      Speak in the tone of a radio drama podcaster.
    • Nada suara sistem: Instruksi harus menggunakan format dan konten tetap. Untuk informasi selengkapnya, lihat Daftar Nada Suara

enable_aigc_tag

bool

Tidak

Tambahkan pengenal AIGC tak terlihat ke audio yang dihasilkan. Saat diatur ke True, pengenal disematkan ke format yang didukung (WAV, MP3, OPUS).

Default: False.

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

Catatan

Atur enable_aigc_tag menggunakan parameter additional_params:

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longanyang",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"enable_aigc_tag": True})

aigc_propagator

str

Tidak

Atur bidang ContentPropagator dalam pengenal AIGC untuk mengidentifikasi propagator konten. Berlaku hanya saat enable_aigc_tag bernilai True.

Default: UID Alibaba Cloud.

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

Catatan

Atur aigc_propagator menggunakan parameter additional_params:

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longanyang",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"enable_aigc_tag": True, "aigc_propagator": "xxxx"})

aigc_propagate_id

str

Tidak

Atur bidang PropagateID dalam pengenal AIGC untuk mengidentifikasi unik sebuah event propagasi. Berlaku hanya saat enable_aigc_tag bernilai True.

Default: ID permintaan dari permintaan sintesis ucapan ini.

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

Catatan

Atur aigc_propagate_id menggunakan parameter additional_params:

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longanyang",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"enable_aigc_tag": True, "aigc_propagate_id": "xxxx"})

hot_fix

dict

Tidak

Konfigurasi hotfix teks untuk menyesuaikan pelafalan kata tertentu atau mengganti teks yang akan disintesis. Hanya suara hasil kloning cosyvoice-v3-flash yang mendukung fitur ini.

Parameter:

  • pronunciation: Sesuaikan pelafalan. Berikan pinyin untuk kata guna memperbaiki pelafalan default yang tidak akurat.

  • replace: Penggantian teks. Ganti kata tertentu dengan teks target sebelum sintesis. Teks yang diganti menjadi input sintesis aktual.

Contoh:

synthesizer = SpeechSynthesizer(
    model="cosyvoice-v3-flash",
    voice="your_voice", # Ganti dengan suara hasil kloning cosyvoice-v3-flash
    hot_fix={
        "pronunciation": [{"weather": "tian1 qi4"}],
        "replace": [{"today": "jin1 tian1"}]
    }
)

enable_markdown_filter

bool

Tidak

Aktifkan penyaringan Markdown. Jika diaktifkan, sistem secara otomatis menyaring simbol Markdown dari teks input sebelum mensintesis ucapan, mencegahnya dibaca sebagai konten teks. Hanya suara hasil kloning cosyvoice-v3-flash yang mendukung fitur ini.

Default: False.

Nilai:

  • True: Aktifkan penyaringan Markdown.

  • False: Nonaktifkan penyaringan Markdown.

Catatan

Atur enable_markdown_filter menggunakan parameter additional_params:

synthesizer = SpeechSynthesizer(
    model="cosyvoice-v3-flash",
    voice="your_voice", # Ganti dengan suara hasil kloning cosyvoice-v3-flash
    additional_params={"enable_markdown_filter": True}
)

callback

ResultCallback

Tidak

Antarmuka callback (ResultCallback).

Antarmuka utama

Kelas SpeechSynthesizer

Impor kelas SpeechSynthesizer menggunakan from dashscope.audio.tts_v2 import *. Kelas ini menyediakan metode inti sintesis ucapan.

Metode

Parameter

Nilai kembali

Deskripsi

def call(self, text: str, timeout_millis=None)
  • text: Teks untuk disintesis

  • timeout_millis: Timeout dalam milidetik untuk memblokir thread. Tidak aktif jika tidak disetel atau disetel ke 0.

Mengembalikan data audio biner jika tidak ada ResultCallback yang ditentukan. Mengembalikan None jika tidak.

Mengonversi seluruh segmen teks (baik teks biasa maupun teks yang berisi SSML) menjadi ucapan.

Dua kasus terjadi saat membuat instans SpeechSynthesizer:

Penting

Sebelum setiap pemanggilan metode call, inisialisasi ulang instans SpeechSynthesizer.

def streaming_call(self, text: str)

text: Fragmen teks untuk disintesis

None

Streaming teks untuk sintesis (SSML tidak didukung).

Panggil metode ini beberapa kali untuk mengirimkan fragmen teks ke server. Dapatkan hasil melalui metode on_data dari antarmuka callback (ResultCallback).

Lihat panggilan streaming dua arah.

def streaming_complete(self, complete_timeout_millis=600000)

complete_timeout_millis: Timeout dalam milidetik

None

Akhiri sintesis ucapan streaming.

Metode ini memblokir thread selama N milidetik (diatur oleh complete_timeout_millis). Jika completeTimeoutMillis bernilai 0, metode ini menunggu tanpa batas.

Secara default, metode ini berhenti menunggu setelah 10 menit.

Lihat panggilan streaming dua arah.

Penting

Dalam panggilan streaming dua arah, selalu panggil metode ini. Jika tidak, ucapan hasil sintesis mungkin hilang.

def get_last_request_id(self)

None

ID permintaan tugas terakhir

Dapatkan ID permintaan tugas terakhir.

def get_first_package_delay(self)

None

Delay paket pertama

Dapatkan delay paket pertama tugas saat ini setelah tugas selesai. Delay paket pertama adalah waktu antara pengiriman teks dan penerimaan paket audio pertama, dalam milidetik.

Faktor yang memengaruhi delay paket pertama:

  • Waktu pembentukan koneksi WebSocket (panggilan pertama)

  • Waktu pemuatan suara (berbeda per suara)

  • Beban layanan (antrian mungkin terjadi saat jam sibuk)

  • Latensi jaringan

Rentang delay khas:

  • Menggunakan kembali koneksi dengan suara sudah dimuat: sekitar 500 ms

  • Koneksi pertama atau pergantian suara: bisa mencapai 1500–2000 ms

Jika delay paket pertama tetap terlalu tinggi (>2000 ms), pertimbangkan:

  1. Menggunakan fitur kolam koneksi dalam skenario konkurensi tinggi untuk membentuk koneksi lebih awal.

  2. Memeriksa kualitas koneksi jaringan.

  3. Menghindari panggilan saat jam sibuk.

def get_response(self)

None

Pesan terakhir

Dapatkan pesan terakhir (format JSON), berguna untuk mendeteksi kesalahan kegagalan tugas.

Antarmuka callback (ResultCallback)

Untuk panggilan streaming satu arah atau panggilan streaming dua arah, server mengembalikan informasi status dan data melalui callback. Anda harus mengimplementasikan metode callback untuk menangani respons server.

Anda dapat mengimpor antarmuka ini menggunakan from dashscope.audio.tts_v2 import *.

Lihat contoh

class Callback(ResultCallback):
    def on_open(self) -> None:
        print('Terhubung')
    
    def on_data(self, data: bytes) -> None:
        # Tangani data audio biner

    def on_complete(self) -> None:
        print('Selesai')

    def on_error(self, message) -> None:
        print('Kesalahan:', message)

    def on_close(self) -> None:
        print('Koneksi ditutup')


callback = Callback()

Metode

Parameter

Nilai kembali

Deskripsi

def on_open(self) -> None

None

None

Dipanggil segera setelah terhubung ke server.

def on_event(self, message: str) -> None

message: Respons server

None

Dipanggil saat server merespons. message adalah string JSON. Uraikan untuk mendapatkan ID tugas (task_id) dan jumlah karakter yang ditagih (characters) untuk permintaan ini.

def on_complete(self) -> None

None

None

Dipanggil setelah semua data sintesis dikembalikan (sintesis ucapan selesai).

def on_error(self, message) -> None

message: Pesan kesalahan

None

Dipanggil saat terjadi kesalahan.

def on_data(self, data: bytes) -> None

data: Data audio biner dari server

None

Dipanggil saat server mengembalikan audio hasil sintesis.

Anda dapat menggabungkan data audio biner menjadi file audio lengkap dan memutarnya dengan pemutar, atau memutarnya secara real-time dengan pemutar yang mendukung streaming.

Penting
  • Dalam sintesis ucapan streaming, untuk format terkompresi seperti MP3/Opus, transmisi audio tersegmentasi memerlukan pemutar streaming. Jangan putar frame demi frame untuk menghindari kegagalan decoding.

    Pemutar yang mendukung pemutaran streaming: ffmpeg, pyaudio (Python), AudioFormat (Java), MediaSource (Javascript), dll.
  • Saat menggabungkan data audio menjadi file audio lengkap, tulis ke file yang sama dalam mode append.

  • Untuk audio WAV/MP3 dalam sintesis ucapan streaming, hanya frame pertama yang berisi informasi header; frame berikutnya hanya berisi data audio.

def on_close(self) -> None

None

None

Dipanggil setelah server menutup koneksi.

Respons

Server mengembalikan data audio biner.

Kode kesalahan

Jika Anda mengalami kesalahan, lihat pesan kesalahan untuk troubleshooting.

Contoh Lainnya

Untuk contoh lainnya, lihat GitHub.

FAQ

Fitur, penagihan, dan pembatasan laju

T: Solusi apa yang bisa saya coba jika mengalami pelafalan tidak akurat?

Anda dapat menyesuaikan efek sintesis ucapan menggunakan SSML.

T: Bagaimana cara memeriksa atau mendapatkan panjang teks untuk setiap sintesis? Penagihan berdasarkan jumlah karakter.

Metode pengambilan tergantung pada apakah logging diaktifkan:

  1. Logging dinonaktifkan

    • Untuk panggilan non-streaming, Anda dapat menghitung panjang secara manual berdasarkan aturan perhitungan karakter.

    • Untuk jenis panggilan lain, Anda dapat mengambil jumlah karakter yang ditagih (characters) dari parameter message metode on_event dalam antarmuka callback (ResultCallback). message adalah string JSON. Gunakan message terakhir yang diterima.

  2. Logging diaktifkan

    Konsol mencetak log yang berisi jumlah karakter yang ditagih. Bidang characters menunjukkan jumlah karakter yang ditagih. Gunakan nilai dari log terakhir yang dicetak.

    2025-08-27 11:02:09,429 - dashscope - speech_synthesizer.py - on_message - 454 - DEBUG - <<<recv {"header":{"task_id":"62ebb7d6cb0a4080868f0edb######","event":"result-generated","attributes":{}},"payload":{"output":{"sentence":{"words":[]}},"usage":{"characters":15}}}

Lihat cara mengaktifkan logging

Anda dapat mengaktifkan logging dengan menyetel variabel lingkungan di command line.

  • Windows: $env:DASHSCOPE_LOGGING_LEVEL="debug"

  • Linux/macOS: export DASHSCOPE_LOGGING_LEVEL=debug

Troubleshooting

Jika kode Anda menghasilkan kesalahan, Anda dapat melakukan troubleshooting menggunakan informasi di Kode kesalahan.

T: Bagaimana cara mendapatkan ID permintaan?

Anda dapat memperolehnya dengan salah satu cara berikut:

T: Mengapa SSML gagal?

Anda dapat melakukan troubleshooting langkah demi langkah:

  1. Konfirmasi bahwa Anda memenuhi semua batasan dan kendala.

  2. Instal SDK DashScope terbaru.

  3. Gunakan metode yang benar. Hanya metode call dari kelas SpeechSynthesizer yang mendukung SSML.

  4. Pastikan teks Anda adalah teks biasa dan memenuhi persyaratan format. Untuk informasi selengkapnya, lihat Ikhtisar SSML.

T: Mengapa saya tidak bisa memutar audio?

Lakukan troubleshooting untuk setiap skenario sebagai berikut:

  1. Skenario: Audio disimpan sebagai file lengkap (misalnya, xx.mp3)

    1. Konsistensi format audio: Pastikan format audio yang ditentukan dalam parameter permintaan sesuai dengan ekstensi file. Misalnya, jika permintaan menentukan format WAV tetapi ekstensi file MP3, pemutaran mungkin gagal.

    2. Kompatibilitas pemutar: Konfirmasi apakah pemutar mendukung format dan laju sampel file audio. Beberapa pemutar mungkin tidak mendukung laju sampel tinggi atau encoding audio tertentu.

  2. Skenario: Pemutaran audio streaming

    1. Simpan aliran audio sebagai file lengkap dan coba putar dengan pemutar. Jika file tidak dapat diputar, rujuk metode troubleshooting di Skenario 1.

    2. Jika file diputar dengan benar, masalah mungkin terletak pada implementasi pemutaran streaming. Konfirmasi apakah pemutar mendukung pemutaran streaming.

      Alat dan pustaka umum yang mendukung pemutaran streaming termasuk ffmpeg, pyaudio (Python), AudioFormat (Java), dan MediaSource (JavaScript).

T: Mengapa pemutaran audio tersendat?

Lakukan troubleshooting untuk setiap skenario sebagai berikut:

  1. Periksa kecepatan pengiriman teks: Pastikan interval yang wajar antara pengiriman teks. Hindari situasi di mana kalimat berikutnya tidak segera dikirim setelah audio sebelumnya selesai diputar.

  2. Periksa performa fungsi callback:

    • Verifikasi bahwa fungsi callback tidak mengandung logika bisnis berlebihan yang menyebabkan blocking.

    • Fungsi callback berjalan pada thread WebSocket. Jika diblokir, hal ini dapat memengaruhi kemampuan WebSocket untuk menerima paket jaringan, menyebabkan audio diterima secara tersendat.

    • Tulis data audio ke buffer audio terpisah dan baca serta proses di thread lain untuk menghindari blocking thread WebSocket.

  3. Periksa stabilitas jaringan: Pastikan koneksi jaringan stabil untuk menghindari gangguan atau penundaan transmisi audio akibat fluktuasi jaringan.

T: Mengapa sintesis ucapan lambat (waktu sintesis lama)?

Lakukan troubleshooting sebagai berikut:

  1. Periksa interval input

    Untuk sintesis ucapan streaming, konfirmasi apakah interval pengiriman teks terlalu lama—misalnya, beberapa detik setelah segmen sebelumnya dikirim sebelum mengirim yang berikutnya. Interval berlebihan meningkatkan total waktu sintesis.

  2. Analisis metrik performa

    • Delay paket pertama: biasanya sekitar 500 ms.

    • RTF (RTF = total waktu sintesis / durasi audio): biasanya kurang dari 1,0.

T: Bagaimana cara menangani pelafalan salah dalam ucapan hasil sintesis?

Gunakan tag SSML <phoneme> untuk menentukan pelafalan yang benar.

T: Mengapa tidak ada audio yang dihasilkan? Mengapa sebagian teks hilang dari audio? (Audio hilang)

Pastikan Anda telah memanggil metode streaming_complete dari kelas SpeechSynthesizer. Server menunggu cukup banyak teks yang dibuffer sebelum memulai sintesis. Jika Anda tidak memanggil metode streaming_complete, teks akhir mungkin tetap tidak diproses.

T: Bagaimana cara memperbaiki kegagalan verifikasi sertifikat SSL?

  1. Instal sertifikat root sistem

    sudo yum install -y ca-certificates
    sudo update-ca-trust enable
  2. Tambahkan kode berikut ke aplikasi Anda

    import os
    os.environ["SSL_CERT_FILE"] = "/etc/ssl/certs/ca-bundle.crt"

T: Mengapa saya mendapatkan “SSL: CERTIFICATE_VERIFY_FAILED” di macOS? (websocket ditutup karena [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000))

Kesalahan verifikasi sertifikat OpenSSL mungkin terjadi saat Anda terhubung ke WebSocket. Hal ini sering disebabkan oleh konfigurasi sertifikat Python yang salah. Anda dapat memperbaiki masalah ini secara manual:

  1. Ekspor sertifikat sistem dan setel variabel lingkungan: Jalankan perintah berikut untuk mengekspor semua sertifikat macOS ke file dan menyetelnya sebagai path default untuk Python dan pustaka terkait.

    security find-certificate -a -p > ~/all_mac_certs.pem
    export SSL_CERT_FILE=~/all_mac_certs.pem
    export REQUESTS_CA_BUNDLE=~/all_mac_certs.pem
  2. Buat tautan simbolik untuk memperbaiki konfigurasi OpenSSL Python: Jika konfigurasi OpenSSL Python tidak memiliki sertifikat, Anda dapat membuat symlink. Ganti path dalam perintah berikut dengan direktori instalasi Python aktual Anda.

    # 3.9 adalah contoh versi. Sesuaikan dengan versi Python yang Anda instal.
    ln -s /etc/ssl/* /Library/Frameworks/Python.framework/Versions/3.9/etc/openssl
  3. Mulai ulang terminal dan bersihkan cache: Tutup dan buka kembali terminal Anda untuk menerapkan variabel lingkungan. Bersihkan cache dan coba kembali koneksi WebSocket.

Langkah-langkah ini dapat menyelesaikan masalah koneksi yang disebabkan oleh salah konfigurasi sertifikat. Jika masalah tetap berlanjut, verifikasi konfigurasi sertifikat server.

T: Mengapa saya mendapatkan “AttributeError: module 'websocket' has no attribute 'WebSocketApp'. Did you mean: 'WebSocket'?”

Kesalahan ini terjadi jika paket websocket-client tidak ada atau terjadi ketidakcocokan versi. Untuk mengatasinya, jalankan perintah berikut:

pip uninstall websocket-client
pip uninstall websocket
pip install websocket-client

Izin dan otentikasi

T: Saya ingin Kunci API saya hanya digunakan untuk layanan sintesis ucapan CosyVoice dan tidak oleh model Model Studio lainnya (isolasi izin). Bagaimana cara melakukannya?

Anda dapat membatasi cakupan Kunci API dengan membuat ruang kerja baru dan hanya mengotorisasi model tertentu. Untuk informasi selengkapnya, lihat Manajemen Ruang Kerja.

Pertanyaan Lainnya

Untuk informasi selengkapnya, lihat QA di GitHub.