全部产品
Search

搜索本产品

    Alibaba Cloud Model Studio：SDK Python sintesis ucapan CosyVoice

    文档中心

    Alibaba Cloud Model Studio：SDK Python sintesis ucapan CosyVoice

    更新时间：Jan 17, 2026

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

    Penting

    Untuk menggunakan model di wilayah China (Beijing), buka halaman API key untuk wilayah China (Beijing).

    Panduan pengguna: Untuk informasi lebih lanjut tentang model dan panduan pemilihan model, lihat Sintesis ucapan Real-time - CosyVoice.

    Prasyarat

    • Anda telah mengaktifkan Model Studio dan membuat API key. Untuk mencegah risiko keamanan, ekspor API key sebagai variabel lingkungan alih-alih menyematkannya langsung di 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 API key jangka panjang, token otentikasi sementara lebih aman karena masa berlakunya singkat (60 detik). Token ini cocok untuk skenario panggilan sementara dan dapat mengurangi risiko kebocoran API key secara efektif.

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

    • Instal versi terbaru SDK DashScope.

    Model dan harga

    Model

    Harga

    Kuota gratis (Catatan)

    cosyvoice-v3-plus

    $0,286706 per 10.000 karakter

    Tidak ada kuota gratis

    cosyvoice-v3-flash

    $0,14335 per 10.000 karakter

    cosyvoice-v2

    $0,286706 per 10.000 karakter

    Batasan teks dan format

    Batas panjang teks

    Aturan penghitungan karakter

    • Satu karakter Tionghoa—termasuk Tionghoa sederhana, Tionghoa tradisional, kanji Jepang, dan hanja Korea—dihitung sebagai 2 karakter. Semua karakter lain, seperti tanda baca, huruf, angka, serta kana atau hangul Jepang/Korea, dihitung sebagai 1 karakter.

    • 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

      • "中文。" → 2(中) + 2(文) + 1(。) = 5 karakter

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

      • "<speak>你好</speak>" → 2(你) + 2(好) = 4 karakter

    Format pengkodean

    Gunakan pengkodean UTF-8.

    Dukungan ekspresi matematika

    Fitur penguraian ekspresi matematika saat ini hanya tersedia untuk model cosyvoice-v2, cosyvoice-v3-flash, dan cosyvoice-v3-plus. Fitur ini mendukung ekspresi matematika umum dari sekolah dasar dan menengah, seperti aritmetika dasar, aljabar, dan geometri.

    Lihat Formula LaTeX ke Ucapan.

    SSML dukungan

    Fitur Speech Synthesis Markup Language (SSML) saat ini hanya tersedia untuk voice kloning model cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2, serta voice sistem yang ditandai sebagai didukung dalam daftar voice. Syarat-syarat berikut harus dipenuhi:

    Memulai

    Kelas SpeechSynthesizer adalah kelas utama untuk sintesis ucapan dan mendukung metode pemanggilan berikut:

    • Panggilan non-streaming: Panggilan blocking yang mengirimkan seluruh teks sekaligus dan langsung mengembalikan audio lengkap. Metode ini cocok untuk skenario sintesis teks pendek.

    • Panggilan streaming unidireksional: Panggilan non-blocking yang mengirimkan seluruh teks sekaligus dan menggunakan fungsi callback untuk menerima data audio, yang mungkin dikirimkan dalam beberapa bagian. Metode ini cocok untuk skenario sintesis teks pendek yang memerlukan latensi rendah.

    • Panggilan streaming bidireksional: Panggilan non-blocking yang mengirimkan teks dalam potongan-potongan dan menggunakan fungsi callback untuk menerima aliran audio hasil sintesis secara bertahap secara real-time. Metode ini cocok untuk skenario sintesis teks panjang yang memerlukan latensi rendah.

    Panggilan Npn-streaming

    Metode ini mengirimkan satu tugas sintesis ucapan tanpa menggunakan fungsi callback. Sintesis tidak mengalirkan hasil antara. Sebaliknya, hasil lengkap dikembalikan sekaligus.

    image

    Anda dapat membuat instans kelas SpeechSynthesizer, menyambungkan parameter permintaan, dan memanggil metode call untuk mensintesis teks dan mengambil data audio biner.

    Teks yang Anda kirimkan tidak boleh lebih dari 2.000 karakter. Untuk informasi lebih lanjut, lihat metode call dari kelas SpeechSynthesizer.

    Penting

    Sebelum setiap pemanggilan metode call, Anda harus membuat instans SpeechSynthesizer yang baru.

    Klik untuk melihat contoh lengkap

    # coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *

# Jika Anda belum mengonfigurasi API key sebagai variabel lingkungan, ganti "your-api-key" dengan API key Anda.
# dashscope.api_key = "your-api-key"

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

# Buat instans SpeechSynthesizer dan masukkan parameter permintaan seperti model dan voice di konstruktor.
synthesizer = SpeechSynthesizer(model=model, voice=voice)
# Kirimkan teks yang akan disintesis dan dapatkan data audio biner.
audio = synthesizer.call("What is the weather like today?")
# Saat pertama kali mengirim teks, koneksi WebSocket harus dibuat. Oleh karena itu, latensi paket pertama mencakup waktu pembuatan koneksi.
print('[Metric] Request ID: {}, First-packet latency: {} 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)

    Pemanggilan streaming unidireksional

    Metode ini mengirimkan satu tugas sintesis ucapan. Hasil antara dialirkan melalui callback, dan hasil sintesis akhir dialirkan melalui fungsi callback ResultCallback.

    image

    Anda dapat membuat instans kelas SpeechSynthesizer, menyambungkan parameter permintaan dan antarmuka ResultCallback, lalu memanggil metode call untuk melakukan sintesis. Anda kemudian dapat mengambil hasil sintesis real-time melalui metode on_data dari antarmuka ResultCallback.

    Panjang teks yang dikirimkan tidak boleh melebihi 2.000 karakter. Untuk informasi lebih lanjut, lihat metode call dari kelas SpeechSynthesizer.

    Penting

    Sebelum setiap pemanggilan metode call, Anda harus membuat instans SpeechSynthesizer yang baru.

    Klik untuk melihat contoh lengkap

    # coding=utf-8

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

# Jika Anda belum mengonfigurasi API key sebagai variabel lingkungan, ganti "your-api-key" dengan API key Anda.
# dashscope.api_key = "your-api-key"

# 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 berhasil dibuat: " + get_timestamp())

    def on_complete(self):
        print("Sintesis ucapan selesai. Seluruh hasil telah diterima: " + get_timestamp())
        # Hanya setelah tugas selesai (callback on_complete dipicu), panggil get_first_package_delay untuk mendapatkan latensi.
        # Saat pertama kali mengirim teks, koneksi WebSocket harus dibuat. Oleh karena itu, latensi paket pertama mencakup waktu pembuatan koneksi.
        print('[Metric] Request ID: {}, First-packet latency: {} ms'.format(
            synthesizer.get_last_request_id(),
            synthesizer.get_first_package_delay()))

    def on_error(self, message: str):
        print(f"Terjadi kesalahan selama 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 data audio biner: " + str(len(data)))
        self.file.write(data)


callback = Callback()

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

# Kirimkan teks untuk sintesis dan terima data audio biner secara real-time di metode on_data callback.
synthesizer.call("What is the weather like today?")

    Panggilan streaming bidireksional

    Metode ini memungkinkan Anda mengirimkan teks dalam beberapa bagian dalam satu tugas sintesis ucapan dan menerima hasil sintesis secara real-time melalui callback.

    Catatan

    • Untuk mengalirkan input, panggil metode streaming_call beberapa kali untuk mengirimkan potongan teks secara berurutan. Server secara otomatis membagi potongan teks menjadi kalimat setelah menerimanya:

      • Kalimat lengkap langsung disintesis.

      • Kalimat yang belum lengkap disimpan dalam buffer dan disintesis setelah menjadi lengkap.

      Saat Anda memanggil metode streaming_complete, server mensintesis seluruh potongan teks yang telah diterima tetapi belum diproses, termasuk kalimat yang belum lengkap.

    • Interval antar pengiriman potongan teks tidak boleh melebihi 23 detik. Jika tidak, terjadi pengecualian "request timeout after 23 seconds".

      Jika tidak ada lagi teks yang akan dikirim, Anda harus memanggil metode streaming_complete untuk mengakhiri tugas.

      Server menerapkan timeout 23 detik. Klien tidak dapat mengubah konfigurasi ini.
    image

    1. Anda dapat membuat instans kelas SpeechSynthesizer.

      Buat instans kelas SpeechSynthesizer dan sambungkan parameter permintaan dan antarmuka callback ResultCallback.

    2. Mengalirkan data

      Alirkan data dengan memanggil metode streaming_call dari kelas SpeechSynthesizer beberapa kali. Ini mengirimkan teks yang akan disintesis ke sisi server secara bertahap.

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

      Panjang segmen teks (parameter text) yang dikirimkan dalam setiap pemanggilan metode streaming_call tidak boleh melebihi 2.000 karakter. Panjang kumulatif seluruh teks yang Anda kirimkan tidak boleh melebihi 200.000 karakter.

    3. Pemrosesan selesai.

      Akhiri proses dengan memanggil metode streaming_complete dari kelas SpeechSynthesizer untuk mengakhiri tugas sintesis ucapan.

      Metode ini memblokir thread saat ini hingga metode on_complete atau on_error dari antarmuka ResultCallback dipicu.

      Anda harus memanggil metode ini. Jika tidak, bagian akhir teks mungkin tidak berhasil disintesis.

    Klik untuk melihat contoh lengkap

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

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

# Jika Anda belum mengonfigurasi API key sebagai variabel lingkungan, ganti "your-api-key" dengan API key Anda.
# dashscope.api_key = "your-api-key"

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


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

    def on_open(self):
        print("Koneksi berhasil dibuat: " + 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. Seluruh hasil telah diterima: " + get_timestamp())

    def on_error(self, message: str):
        print(f"Terjadi kesalahan selama 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 data audio biner: " + str(len(data)))
        self._stream.write(data)


callback = Callback()

test_text = [
    "The streaming text-to-speech SDK ",
    "can convert input text ",
    "into binary speech data. ",
    "Compared to non-streaming speech synthesis, ",
    "the advantage of streaming synthesis is its lower latency. ",
    "Users can hear nearly synchronous speech output ",
    "while inputting text, ",
    "which greatly improves the interactive experience ",
    "and reduces user waiting time. ",
    "It is suitable for scenarios that call a large ",
    "language model (LLM) to perform ",
    "speech synthesis with streaming text input.",
]

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


# Alirkan teks yang akan disintesis. Terima data audio biner secara real-time di metode on_data antarmuka callback.
for text in test_text:
    synthesizer.streaming_call(text)
    time.sleep(0.1)
# Akhiri sintesis ucapan streaming.
synthesizer.streaming_complete()

# Saat pertama kali mengirim teks, koneksi WebSocket harus dibuat. Oleh karena itu, latensi paket pertama mencakup waktu pembuatan koneksi.
print('[Metric] Request ID: {}, First-packet latency: {} 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.

    Model berbeda memerlukan voice yang sesuai:

    • cosyvoice-v3-flash/cosyvoice-v3-plus: Gunakan voice seperti longanyang.

    • cosyvoice-v2: Gunakan voice seperti longxiaochun_v2.

    • Untuk daftar lengkap, lihat Daftar voice.

    voice

    str

    Ya

    Voice yang digunakan untuk sintesis ucapan.

    Voice sistem dan voice kloning didukung:

    • Voice sistem: Lihat Daftar voice.

    • Voice kloning: Sesuaikan voice menggunakan fitur kloning suara. Saat menggunakan voice kloning, pastikan akun yang sama digunakan untuk kloning suara dan sintesis ucapan. Untuk langkah-langkah detail, lihat API kloning suara CosyVoice.

      Saat menggunakan voice kloning, nilai parameter model dalam permintaan harus persis sama dengan versi model yang digunakan untuk membuat voice tersebut (parameter target_model).

    format

    enum

    Tidak

    Menentukan format pengkodean audio dan laju sampel.

    Jika format tidak ditentukan, audio hasil sintesis memiliki laju sampel 22,05 kHz dan dalam format MP3.

    Catatan

    Laju sampel default adalah laju optimal untuk voice saat ini. Secara default, output menggunakan laju sampel ini. Downsampling dan upsampling juga didukung.

    Format pengkodean audio dan laju sampel berikut dapat ditentukan:

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

      • AudioFormat.WAV_8000HZ_MONO_16BIT: Format audio WAV dan laju sampel 8 kHz.

      • AudioFormat.WAV_16000HZ_MONO_16BIT: Format audio WAV dan laju sampel 16 kHz.

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

      • AudioFormat.WAV_24000HZ_MONO_16BIT: Format audio WAV dan laju sampel 24 kHz.

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

      • AudioFormat.WAV_48000HZ_MONO_16BIT: Format audio WAV dan laju sampel 48 kHz.

      • AudioFormat.MP3_8000HZ_MONO_128KBPS: Format audio MP3 dan laju sampel 8 kHz.

      • AudioFormat.MP3_16000HZ_MONO_128KBPS: Format audio MP3 dan laju sampel 16 kHz.

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

      • AudioFormat.MP3_24000HZ_MONO_256KBPS: Format audio MP3 dan laju sampel 24 kHz.

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

      • AudioFormat.MP3_48000HZ_MONO_256KBPS: Format audio MP3 dan laju sampel 48 kHz.

      • AudioFormat.PCM_8000HZ_MONO_16BIT: Format audio PCM dan laju sampel 8 kHz.

      • AudioFormat.PCM_16000HZ_MONO_16BIT: Format audio PCM dan laju sampel 16 kHz.

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

      • AudioFormat.PCM_24000HZ_MONO_16BIT: Format audio PCM dan laju sampel 24 kHz.

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

      • AudioFormat.PCM_48000HZ_MONO_16BIT: Format audio PCM dan laju sampel 48 kHz.

    • Saat format audio adalah Opus, sesuaikan bitrate menggunakan parameter bit_rate. Fitur ini hanya tersedia di SDK DashScope versi 1.24.0 dan lebih baru.

      • AudioFormat.OGG_OPUS_8KHZ_MONO_32KBPS: Format audio Opus, laju sampel 8 kHz, dan bitrate 32 kbps.

      • AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS: Format audio Opus, laju sampel 16 kHz, dan bitrate 16 kbps.

      • AudioFormat.OGG_OPUS_16KHZ_MONO_32KBPS: Format audio Opus, laju sampel 16 kHz, dan bitrate 32 kbps.

      • AudioFormat.OGG_OPUS_16KHZ_MONO_64KBPS: Format audio Opus, laju sampel 16 kHz, dan bitrate 64 kbps.

      • AudioFormat.OGG_OPUS_24KHZ_MONO_16KBPS: Format audio Opus, laju sampel 24 kHz, dan bitrate 16 kbps.

      • AudioFormat.OGG_OPUS_24KHZ_MONO_32KBPS: Format audio Opus, laju sampel 24 kHz, dan bitrate 32 kbps.

      • AudioFormat.OGG_OPUS_24KHZ_MONO_64KBPS: Format audio Opus, laju sampel 24 kHz, dan bitrate 64 kbps.

      • AudioFormat.OGG_OPUS_48KHZ_MONO_16KBPS: Format audio Opus, laju sampel 48 kHz, dan bitrate 16 kbps.

      • AudioFormat.OGG_OPUS_48KHZ_MONO_32KBPS: Format audio Opus, laju sampel 48 kHz, dan bitrate 32 kbps.

      • AudioFormat.OGG_OPUS_48KHZ_MONO_64KBPS: Format audio Opus, laju sampel 48 kHz, dan bitrate 64 kbps.

    volume

    int

    Tidak

    Volume.

    Nilai default: 50.

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

    Penting

    Bidang ini berbeda di berbagai versi SDK DashScope:

    • SDK versi 1.20.10 dan lebih baru: volume

    • Versi SDK sebelum 1.20.10: volume

    speech_rate

    float

    Tidak

    Laju ucapan.

    Nilai default: 1,0.

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

    pitch_rate

    float

    Tidak

    Pitch. Nilai ini adalah pengali untuk penyesuaian pitch. Hubungan antara nilai ini dan pitch yang dirasakan tidak sepenuhnya linear atau logaritmik. Uji berbagai nilai untuk menemukan yang terbaik.

    Nilai default: 1,0.

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

    bit_rate

    int

    Tidak

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

    Nilai default: 32.

    Rentang nilai: [6, 510].

    Catatan

    bit_rate harus diatur 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

    Menentukan apakah timestamp tingkat kata diaktifkan.

    Nilai default: False.

    • True

    • False

    Fitur ini hanya berlaku untuk voice kloning model cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2, serta voice sistem dalam Daftar voice yang ditandai sebagai didukung.

    Hasil timestamp hanya dapat diambil melalui antarmuka callback.
    Catatan

    word_timestamp_enabled harus diatur menggunakan parameter additional_params:

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

    Klik untuk melihat 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


# Jika Anda belum mengonfigurasi API key sebagai variabel lingkungan, ganti "your-api-key" dengan API key Anda.
# dashscope.api_key = "your-api-key"

# Hanya model cosyvoice-v2 yang didukung.
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 berhasil dibuat: " + get_timestamp())

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

    def on_error(self, message: str):
        print(f"Terjadi kesalahan selama 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 nomor kalimat.
            # index = sentence['index']
            words = sentence['words']
            if words:
                for word in words:
                    print(f'word: {word}')
                    # Contoh nilai: word: {'text': 'What', 'begin_index': 0, 'end_index': 1, 'begin_time': 80, 'end_time': 200}

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


callback = Callback()

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

# Kirimkan teks yang akan disintesis dan terima data audio biner secara real-time di metode on_data antarmuka callback.
synthesizer.call("What is the weather like today?")
# Saat pertama kali mengirim teks, koneksi WebSocket harus dibuat. Oleh karena itu, latensi paket pertama mencakup waktu pembuatan koneksi.
print('[Metric] Request ID: {}, First-packet latency: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

    seed

    int

    Tidak

    Seed bilangan acak yang digunakan selama generasi, yang memvariasikan efek sintesis. Jika versi model, teks, voice, dan parameter lainnya sama, penggunaan seed yang sama akan mereproduksi hasil sintesis yang identik.

    Nilai default: 0.

    Rentang nilai: [0, 65535].

    language_hints

    list[str]

    Tidak

    Menentukan bahasa target untuk sintesis ucapan guna meningkatkan efek sintesis.

    Gunakan parameter ini ketika pelafalan angka, singkatan, atau simbol, atau ketika efek sintesis untuk bahasa non-Tionghoa tidak sesuai harapan.

    Nilai yang valid:

    • zh: Tionghoa

    • en: Inggris

    • fr: Prancis

    • de: Jerman

    • ja: Jepang

    • ko: Korea

    • ru: Rusia

    Catatan: Meskipun parameter ini berupa array, versi saat ini hanya memproses elemen pertama. Oleh karena itu, Anda hanya boleh mengirimkan satu nilai.

    Penting

    Parameter ini menentukan bahasa target untuk sintesis ucapan. Pengaturan ini independen dari bahasa audio sampel yang digunakan untuk kloning suara. Untuk mengatur bahasa sumber dalam tugas kloning suara, lihat API kloning suara CosyVoice.

    instruction

    str

    Tidak

    Set instruction: Fitur ini hanya tersedia untuk voice kloning model cosyvoice-v3-flash dan cosyvoice-v3-plus, serta voice sistem yang ditandai sebagai didukung dalam Daftar voice.

    Tidak ada nilai default. Parameter ini tidak berpengaruh jika tidak diatur.

    Sintesis ucapan memiliki efek berikut:

    1. Menentukan dialek (hanya untuk voice kloning)

      • Format: "请用<方言>表达。" (Catatan: Jangan menghilangkan titik (。) di akhir. Ganti <方言> dengan 方言 tertentu, seperti 广东话.)

      • Contoh: "请用广东话表达。"

      • Dialek yang didukung: 广东话 (Kanton), 东北话 (Dongbei), 甘肃话 (Gansu), 贵州话 (Guizhou), 河南话 (Henan), 湖北话 (Hubei), 江西话 (Jiangxi), 闽南话 (Minnan), 宁夏话 (Ningxia), 山西话 (Shanxi), 陕西话 (Shaanxi), 山东话 (Shandong), 上海话 (Shanghainese), 四川话 (Sichuan), 天津话 (Tianjin), dan 云南话 (Yunnan).

    2. Menentukan emosi, skenario, peran, atau identitas. Hanya beberapa voice sistem yang mendukung fitur ini, dan bervariasi tergantung voice-nya. Lihat Daftar voice.

    enable_aigc_tag

    bool

    Tidak

    Menentukan apakah akan menambahkan identifier AIGC tak terlihat ke audio yang dihasilkan. Jika diatur ke True, identifier tak terlihat tersebut disematkan ke audio untuk format yang didukung (WAV, MP3, dan Opus).

    Nilai default: False.

    Fitur ini hanya didukung oleh model cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2.

    Catatan

    enable_aigc_tag harus diatur 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

    Mengatur bidang ContentPropagator dalam identifier AIGC tak terlihat untuk mengidentifikasi propagator konten. Parameter ini hanya berlaku jika enable_aigc_tag bernilai True.

    Nilai default: UID Alibaba Cloud.

    Fitur ini hanya didukung oleh model cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2.

    Catatan

    aigc_propagator harus diatur 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

    Mengatur bidang PropagateID dalam identifier AIGC tak terlihat untuk mengidentifikasi secara unik tindakan propagasi tertentu. Parameter ini hanya berlaku jika enable_aigc_tag bernilai True.

    Nilai default: Request ID dari permintaan sintesis ucapan saat ini.

    Fitur ini hanya didukung oleh model cosyvoice-v3-flash, cosyvoice-v3-plus, dan cosyvoice-v2.

    Catatan

    aigc_propagate_id harus diatur 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"})

    callback

    ResultCallback

    Tidak

    Antarmuka ResultCallback.

    Antarmuka utama

    Kelas SpeechSynthesizer

    Kelas SpeechSynthesizer adalah antarmuka utama untuk sintesis ucapan. Anda dapat mengimpor kelas ini menggunakan from dashscope.audio.tts_v2 import *.

    Metode

    Parameter

    Nilai kembali

    Deskripsi

    def call(self, text: str, timeout_millis=None)

    • text: Teks yang akan disintesis.

    • timeout_millis: Timeout dalam milidetik untuk thread blocking. Parameter ini tidak berlaku jika tidak diatur atau diatur ke 0.

    Mengembalikan data audio biner jika ResultCallback tidak ditentukan. Jika tidak, mengembalikan None.

    Mengubah seluruh segmen teks menjadi ucapan. Teks dapat berupa teks biasa atau berisi SSML.

    Saat membuat instans SpeechSynthesizer, dua skenario mungkin terjadi:

    • Jika Anda tidak menentukan ResultCallback, metode call memblokir thread saat ini hingga sintesis ucapan selesai dan mengembalikan data audio biner. Untuk informasi lebih lanjut, lihat panggilan non-streaming.

    • Jika Anda menentukan ResultCallback, metode call langsung mengembalikan None. Hasil sintesis ucapan dikembalikan melalui metode on_data dari antarmuka ResultCallback. Untuk informasi lebih lanjut, lihat panggilan streaming unidireksional.

    Penting

    Sebelum setiap pemanggilan metode call, Anda harus membuat instans SpeechSynthesizer yang baru.

    def streaming_call(self, text: str)

    text: Segmen teks yang akan disintesis.

    None

    Mengalirkan teks untuk disintesis. Teks yang berisi SSML tidak didukung.

    Anda dapat memanggil antarmuka ini beberapa kali untuk mengirimkan teks yang akan disintesis ke server secara bertahap. Hasil sintesis diambil melalui metode on_data dari antarmuka ResultCallback.

    Untuk informasi lebih lanjut, lihat Panggilan streaming bidireksional.

    def streaming_complete(self, complete_timeout_millis=600000)

    complete_timeout_millis: Waktu tunggu dalam milidetik.

    None

    Mengakhiri sintesis ucapan streaming.

    Metode ini memblokir thread saat ini selama durasi yang ditentukan oleh complete_timeout_millis hingga tugas selesai. Jika completeTimeoutMillis diatur ke 0, thread menunggu tanpa batas.

    Secara default, tunggu berhenti jika waktu tunggu melebihi 10 menit.

    Untuk informasi lebih lanjut, lihat Panggilan streaming bidireksional.

    Penting

    Saat melakukan panggilan streaming bidireksional, panggil metode ini. Jika tidak, ucapan yang disintesis mungkin tidak lengkap.

    def get_last_request_id(self)

    None

    ID permintaan tugas terakhir.

    Mendapatkan ID permintaan tugas terakhir.

    def get_first_package_delay(self)

    None

    Latensi paket pertama

    Mendapatkan latensi paket pertama. Latensi biasanya sekitar 500 ms.

    Latensi paket pertama adalah waktu dalam milidetik dari saat Anda mengirim teks hingga menerima paket audio pertama. Periksa latensi setelah tugas selesai.

    Saat pertama kali mengirim teks, koneksi WebSocket harus dibuat. Oleh karena itu, latensi paket pertama mencakup waktu yang diperlukan untuk membuat koneksi.

    def get_response(self)

    None

    Pesan terakhir

    Mendapatkan pesan terakhir, yang dalam format JSON. Anda dapat menggunakannya untuk mengambil error kegagalan tugas.

    Antarmuka callback (ResultCallback)

    Untuk panggilan streaming unidireksional atau panggilan streaming bidireksional, server mengembalikan informasi dan data proses penting ke klien melalui callback. Anda harus mengimplementasikan metode callback untuk memproses informasi dan data yang dikembalikan.

    Anda dapat mengimpornya menggunakan from dashscope.audio.tts_v2 import *.

    Klik untuk melihat contoh

    class Callback(ResultCallback):
    def on_open(self) -> None:
        print('Koneksi berhasil')
    
    def on_data(self, data: bytes) -> None:
        # Implementasikan logika untuk menerima hasil audio biner yang disintesis.

    def on_complete(self) -> None:
        print('Sintesis selesai')

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

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


callback = Callback()

    Metode

    Parameter

    Nilai kembali

    Deskripsi

    def on_open(self) -> None

    None

    None

    Metode ini dipanggil segera setelah koneksi dengan server berhasil dibuat.

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

    message: Informasi yang dikembalikan oleh server.

    None

    Metode ini dipanggil saat layanan mengirimkan respons. message adalah string JSON. Uraikan string tersebut untuk mendapatkan informasi seperti ID tugas (parameter task_id) dan jumlah karakter yang dikenai biaya dalam permintaan (parameter characters).

    def on_complete(self) -> None

    None

    None

    Metode ini dipanggil setelah seluruh data hasil sintesis dikembalikan dan sintesis ucapan selesai.

    def on_error(self, message) -> None

    message: Pesan error.

    None

    Metode ini dipanggil saat terjadi pengecualian.

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

    data: Data audio biner yang dikembalikan oleh server.

    None

    Metode ini dipanggil saat server mengembalikan audio hasil sintesis.

    Gabungkan data audio biner menjadi file audio lengkap untuk diputar, atau putar secara real-time dengan pemutar yang mendukung pemutaran streaming.

    Penting

    • Dalam sintesis ucapan streaming, untuk format terkompresi seperti MP3 dan Opus, gunakan pemutar streaming untuk memutar segmen audio. Jangan memutarnya frame demi frame untuk menghindari kegagalan decoding.

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

    • Saat menggabungkan data audio menjadi file audio lengkap, tambahkan data tersebut ke file yang sama.

    • Untuk format audio WAV dan 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

    Metode ini dipanggil setelah layanan menutup koneksi.

    Respons

    Server mengembalikan data audio biner:

    Kode error

    Untuk informasi troubleshooting, lihat Pesan error.

    Contoh lainnya

    Untuk contoh lainnya, lihat GitHub.

    FAQ

    Fitur, penagihan, dan pembatasan laju

    T: Apa yang bisa saya lakukan untuk memperbaiki pelafalan yang tidak akurat?

    Anda dapat menggunakan SSML untuk menyesuaikan output sintesis ucapan.

    T: Sintesis ucapan ditagih berdasarkan jumlah karakter teks. Bagaimana cara melihat atau mendapatkan panjang teks untuk setiap sintesis?

    Ini tergantung pada apakah logging diaktifkan:

    1. Logging dinonaktifkan.

      • Untuk panggilan non-streaming, Anda dapat menghitung jumlah karakter sesuai aturan penghitungan karakter.

      • Atau, Anda dapat mengambil informasi dari parameter message dari metode on_event dari antarmuka callback ResultCallback. message adalah string JSON yang dapat Anda uraikan untuk mengambil jumlah karakter yang dikenai biaya untuk permintaan saat ini dari parameter characters. Gunakan message terakhir yang Anda terima.

    2. Logging diaktifkan.

      Jika logging diaktifkan, konsol mencetak log yang berisi parameter characters. Parameter ini menunjukkan jumlah karakter yang dikenai biaya untuk permintaan tersebut. Gunakan nilai dari entri log terakhir untuk permintaan tersebut.

      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}}}

    Klik untuk melihat cara mengaktifkan logging

    Anda dapat mengaktifkan logging dengan mengatur variabel lingkungan di command line:

    • Windows: $env:DASHSCOPE_LOGGING_LEVEL="debug"

    • Linux/macOS: export DASHSCOPE_LOGGING_LEVEL=debug

    Troubleshooting

    Jika Anda mengalami error kode, rujuk Kode error untuk memecahkan masalah.

    T: Bagaimana cara mendapatkan Request ID?

    Anda dapat mengambilnya dengan salah satu dari dua cara berikut:

    T: Mengapa fitur SSML gagal?

    Periksa hal-hal berikut:

    1. Pastikan cakupan benar.

    2. Pastikan Anda telah menginstal versi terbaru SDK DashScope.

    3. Pastikan Anda menggunakan antarmuka yang benar. SSML hanya didukung oleh metode call dari kelas SpeechSynthesizer.

    4. Pastikan teks untuk sintesis berupa teks biasa dan memenuhi format yang diperlukan. Untuk informasi lebih lanjut, lihat Pengenalan SSML.

    T: Mengapa audio tidak bisa diputar?

    Pecahkan masalah ini berdasarkan skenario berikut:

    1. Audio disimpan sebagai file lengkap, seperti file .mp3.

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

      2. Kompatibilitas pemutar: Pastikan pemutar Anda mendukung format dan laju sampel file audio tersebut. Misalnya, beberapa pemutar mungkin tidak mendukung laju sampel tinggi atau pengkodean audio tertentu.

    2. Audio diputar dalam mode streaming.

      1. Simpan aliran audio sebagai file lengkap dan coba putar. Jika file gagal diputar, lihat langkah troubleshooting untuk skenario pertama.

      2. Jika file dapat diputar dengan benar, masalahnya mungkin terletak pada implementasi pemutaran streaming. Pastikan pemutar Anda 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?

    Pecahkan masalah ini berdasarkan skenario berikut:

    1. Periksa kecepatan pengiriman teks: Pastikan interval pengiriman teks wajar. Hindari penundaan dalam mengirimkan segmen teks berikutnya setelah audio untuk segmen sebelumnya selesai diputar.

    2. Periksa performa fungsi callback:

      • Periksa apakah fungsi callback berisi logika bisnis berlebihan yang dapat menyebabkannya terblokir.

      • Fungsi callback berjalan di thread WebSocket. Jika thread ini terblokir, hal tersebut dapat mengganggu kemampuan WebSocket untuk menerima paket jaringan, sehingga menyebabkan audio tersendat.

      • Untuk menghindari pemblokiran thread WebSocket, tulis data audio ke buffer audio terpisah lalu gunakan thread lain untuk membaca dan memprosesnya.

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

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

    Lakukan langkah troubleshooting berikut:

    1. Periksa interval input

      Jika Anda menggunakan sintesis ucapan streaming, periksa apakah interval pengiriman teks terlalu lama. Misalnya, penundaan beberapa detik sebelum mengirimkan segmen berikutnya akan meningkatkan total waktu sintesis.

    2. Analisis metrik performa

      • Latensi paket pertama: Biasanya sekitar 500 ms.

      • Faktor Real-Time (RTF): Dihitung sebagai Total Waktu Sintesis / Durasi Audio. RTF biasanya kurang dari 1,0.

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

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

    T: Mengapa tidak ada ucapan yang dikembalikan? Mengapa bagian akhir teks tidak berhasil dikonversi menjadi ucapan? (Ucapan hasil sintesis hilang)

    Periksa apakah Anda memanggil metode streaming_complete dari kelas SpeechSynthesizer. Server menyimpan teks dalam cache dan mulai mensintesis hanya setelah menerima cukup teks. Jika Anda tidak memanggil metode streaming_complete, teks yang tersisa dalam cache mungkin tidak disintesis.

    T: Bagaimana cara menangani kegagalan verifikasi sertifikat SSL?

    1. Instal sertifikat root sistem.

      sudo yum install -y ca-certificates
sudo update-ca-trust enable

    2. Tambahkan konten berikut ke kode Anda.

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

    T: Apa penyebab pengecualian "SSL: CERTIFICATE_VERIFY_FAILED" pada macOS? (websocket ditutup karena [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000))

    Saat menghubungkan ke WebSocket, Anda mungkin mengalami kegagalan verifikasi sertifikat OpenSSL dengan pesan yang menunjukkan bahwa sertifikat tidak dapat ditemukan. Hal ini biasanya terjadi karena konfigurasi sertifikat yang salah di lingkungan Python. Ikuti langkah-langkah berikut untuk menemukan dan memperbaiki masalah sertifikat secara manual:

    1. Ekspor sertifikat sistem dan atur variabel lingkungan. Jalankan perintah berikut untuk mengekspor semua sertifikat dari sistem macOS Anda ke file dan atur file ini sebagai jalur sertifikat default untuk Python dan pustaka terkaitnya:

      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 Anda tidak memiliki sertifikat, jalankan perintah berikut untuk membuat tautan simbolik. Pastikan untuk mengganti path dalam perintah dengan path instalasi aktual versi Python lokal Anda:

      # 3.9 adalah contoh nomor versi. Sesuaikan path sesuai versi Python yang terinstal di lokal Anda.
ln -s /etc/ssl/* /Library/Frameworks/Python.framework/Versions/3.9/etc/openssl

    3. Mulai ulang terminal dan bersihkan cache. Setelah menyelesaikan langkah-langkah di atas, tutup dan buka kembali terminal untuk memastikan variabel lingkungan berlaku. Bersihkan cache apa pun yang mungkin ada dan coba sambungkan kembali ke WebSocket.

    Langkah-langkah ini seharusnya dapat menyelesaikan masalah koneksi yang disebabkan oleh konfigurasi sertifikat yang salah. Jika masalah tetap berlanjut, periksa apakah konfigurasi sertifikat di server target sudah benar.

    T: Apa penyebab error "AttributeError: module 'websocket' has no attribute 'WebSocketApp'. Did you mean: 'WebSocket'?" saat menjalankan kode?

    Error ini terjadi karena websocket-client tidak terinstal atau versinya tidak sesuai. Jalankan perintah berikut untuk menyelesaikan masalah:

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

    Izin dan otentikasi

    T: Saya ingin API key saya hanya digunakan untuk layanan sintesis ucapan CosyVoice, bukan untuk model Model Studio lainnya (isolasi izin). Apa yang harus saya lakukan?

    Anda dapat membuat ruang kerja dan hanya mengotorisasi model tertentu untuk membatasi cakupan API key. Lihat Kelola ruang kerja.

    Pertanyaan lainnya

    Lihat Q&A di GitHub.