Gunakan sintesis ucapan real-time Qwen menggunakan SDK Python - Alibaba Cloud Model Studio - Alibaba Cloud - Alibaba Cloud Model Studio

Topik ini menjelaskan antarmuka utama dan parameter permintaan untuk memanggil real-time speech synthesis (Qwen) menggunakan DashScope Python SDK.

Panduan pengguna: Untuk pengenalan model dan rekomendasi pemilihan, lihat Real-time speech synthesis – Qwen atau Speech synthesis – Qwen.

Prasyarat

Diperlukan DashScope Python SDK versi 1.25.11 atau yang lebih baru.

Mulai

Server commit mode

import os
import base64
import threading
import time
import dashscope
from dashscope.audio.qwen_tts_realtime import *


qwen_tts_realtime: QwenTtsRealtime = None
text_to_synthesize = [
    'Right? I love supermarkets like this.',
    'Especially during Chinese New Year,',
    'I go shopping at supermarkets.',
    'And I feel',
    'absolutely thrilled!',
    'I want to buy so many things!'
]

DO_VIDEO_TEST = False

def init_dashscope_api_key():
    """
        Set your DashScope API key. More information:
        https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    """

    # API keys differ between the Singapore and Beijing regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  # Load API key from environment variable DASHSCOPE_API_KEY
    else:
        dashscope.api_key = 'your-dashscope-api-key'  # Set API key manually



class MyCallback(QwenTtsRealtimeCallback):
    def __init__(self):
        self.complete_event = threading.Event()
        self.file = open('result_24k.pcm', 'wb')

    def on_open(self) -> None:
        print('connection opened, init player')

    def on_close(self, close_status_code, close_msg) -> None:
        self.file.close()
        print('connection closed with code: {}, msg: {}, destroy player'.format(close_status_code, close_msg))

    def on_event(self, response: str) -> None:
        try:
            global qwen_tts_realtime
            type = response['type']
            if 'session.created' == type:
                print('start session: {}'.format(response['session']['id']))
            if 'response.audio.delta' == type:
                recv_audio_b64 = response['delta']
                self.file.write(base64.b64decode(recv_audio_b64))
            if 'response.done' == type:
                print(f'response {qwen_tts_realtime.get_last_response_id()} done')
            if 'session.finished' == type:
                print('session finished')
                self.complete_event.set()
        except Exception as e:
            print('[Error] {}'.format(e))
            return

    def wait_for_finished(self):
        self.complete_event.wait()


if __name__  == '__main__':
    init_dashscope_api_key()

    print('Initializing ...')

    callback = MyCallback()

    qwen_tts_realtime = QwenTtsRealtime(
        # To use instruction control, replace the model with qwen3-tts-instruct-flash-realtime
        model='qwen3-tts-flash-realtime',
        callback=callback,
        # Singapore region
        url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime'
        )

    qwen_tts_realtime.connect()
    qwen_tts_realtime.update_session(
        voice = 'Cherry',
        response_format = AudioFormat.PCM_24000HZ_MONO_16BIT,
        # To use instruction control, uncomment the following lines and replace the model with qwen3-tts-instruct-flash-realtime
        # instructions='Speak quickly with a rising intonation, suitable for introducing fashion products.',
        # optimize_instructions=True,
        mode = 'server_commit'        
    )
    for text_chunk in text_to_synthesize:
        print(f'send text: {text_chunk}')
        qwen_tts_realtime.append_text(text_chunk)
        time.sleep(0.1)
    qwen_tts_realtime.finish()
    callback.wait_for_finished()
    print('[Metric] session: {}, first audio delay: {}'.format(
                    qwen_tts_realtime.get_session_id(), 
                    qwen_tts_realtime.get_first_audio_delay(),
                    ))

Commit mode

import base64
import os
import threading
import dashscope
from dashscope.audio.qwen_tts_realtime import *


qwen_tts_realtime: QwenTtsRealtime = None
text_to_synthesize = [
    'This is the first sentence.',
    'This is the second sentence.',
    'This is the third sentence.',
]

DO_VIDEO_TEST = False

def init_dashscope_api_key():
    """
        Set your DashScope API key. More information:
        https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    """

    # API keys differ between the Singapore and Beijing regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  # Load API key from environment variable DASHSCOPE_API_KEY
    else:
        dashscope.api_key = 'your-dashscope-api-key'  # Set API key manually



class MyCallback(QwenTtsRealtimeCallback):
    def __init__(self):
        super().__init__()
        self.response_counter = 0
        self.complete_event = threading.Event()
        self.file = open(f'result_{self.response_counter}_24k.pcm', 'wb')

    def reset_event(self):
        self.response_counter += 1
        self.file = open(f'result_{self.response_counter}_24k.pcm', 'wb')
        self.complete_event = threading.Event()

    def on_open(self) -> None:
        print('connection opened, init player')

    def on_close(self, close_status_code, close_msg) -> None:
        print('connection closed with code: {}, msg: {}, destroy player'.format(close_status_code, close_msg))

    def on_event(self, response: str) -> None:
        try:
            global qwen_tts_realtime
            type = response['type']
            if 'session.created' == type:
                print('start session: {}'.format(response['session']['id']))
            if 'response.audio.delta' == type:
                recv_audio_b64 = response['delta']
                self.file.write(base64.b64decode(recv_audio_b64))
            if 'response.done' == type:
                print(f'response {qwen_tts_realtime.get_last_response_id()} done')
                self.complete_event.set()
                self.file.close()
            if 'session.finished' == type:
                print('session finished')
                self.complete_event.set()
        except Exception as e:
            print('[Error] {}'.format(e))
            return

    def wait_for_response_done(self):
        self.complete_event.wait()


if __name__  == '__main__':
    init_dashscope_api_key()

    print('Initializing ...')

    callback = MyCallback()

    qwen_tts_realtime = QwenTtsRealtime(
        # To use instruction control, replace the model with qwen3-tts-instruct-flash-realtime
        model='qwen3-tts-flash-realtime',
        callback=callback, 
        # Singapore region
        url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime'
        )

    qwen_tts_realtime.connect()
    qwen_tts_realtime.update_session(
        voice = 'Cherry',
        response_format = AudioFormat.PCM_24000HZ_MONO_16BIT,
        # To use instruction control, uncomment the following lines and replace the model with qwen3-tts-instruct-flash-realtime
        # instructions='Speak quickly with a rising intonation, suitable for introducing fashion products.',
        # optimize_instructions=True,
        mode = 'commit'        
    )
    print(f'send text: {text_to_synthesize[0]}')
    qwen_tts_realtime.append_text(text_to_synthesize[0])
    qwen_tts_realtime.commit()
    callback.wait_for_response_done()
    callback.reset_event()
    
    print(f'send text: {text_to_synthesize[1]}')
    qwen_tts_realtime.append_text(text_to_synthesize[1])
    qwen_tts_realtime.commit()
    callback.wait_for_response_done()
    callback.reset_event()

    print(f'send text: {text_to_synthesize[2]}')
    qwen_tts_realtime.append_text(text_to_synthesize[2])
    qwen_tts_realtime.commit()
    callback.wait_for_response_done()
    
    qwen_tts_realtime.finish()
    print('[Metric] session: {}, first audio delay: {}'.format(
                    qwen_tts_realtime.get_session_id(), 
                    qwen_tts_realtime.get_first_audio_delay(),
                    ))

Kunjungi GitHub untuk mengunduh contoh kode tambahan.

Parameter permintaan

Tetapkan parameter berikut dalam konstruktor QwenTtsRealtime:

Parameter	Type	Wajib	Deskripsi
model	str	Ya	Nama model (lihat Model yang didukung).
url	str	Ya	China (Beijing): `wss://dashscope.aliyuncs.com/api-ws/v1/realtime` Singapura: `wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime`

Konfigurasikan parameter berikut menggunakan update_session:

Parameter	Type	Wajib	Deskripsi
voice	str	Ya	Voice untuk sintesis suara. Untuk informasi selengkapnya, lihat Voice yang didukung. Mendukung suara sistem dan suara kustom: Voice sistem: Hanya tersedia untuk seri model Qwen3-TTS-Instruct-Flash-Realtime, Qwen3-TTS-Flash-Realtime, dan Qwen-TTS-Realtime. Untuk contoh voice, lihat Voice yang didukung. Custom Voice Voice yang dikustomisasi melalui fitur Voice Cloning (Qwen): Hanya tersedia untuk seri model Qwen3-TTS-VC-Realtime. Voice yang dikustomisasi melalui fitur Voice Design (Qwen): Hanya tersedia untuk seri model Qwen3-TTS-VD-Realtime.
language_type	str	Tidak	Menentukan bahasa audio hasil sintesis. Nilai default adalah `Auto`. `Auto`: Gunakan nilai ini ketika bahasa teks tidak pasti atau mengandung beberapa bahasa. Model secara otomatis mencocokkan pelafalan untuk segmen bahasa berbeda dalam teks, tetapi tidak menjamin akurasi sempurna. Bahasa tertentu: Gunakan ini untuk teks berbahasa tunggal. Menentukan bahasa secara signifikan meningkatkan kualitas sintesis dan biasanya menghasilkan hasil yang lebih baik daripada `Auto`. Nilai yang valid meliputi: `Chinese` `English` `German` `Italian` `Portuguese` `Spanish` `Japanese` `Korean` `French` `Russian`
mode	str	Tidak	Mode interaksi. Nilai yang valid: `server_commit` (default): Server secara otomatis menentukan kapan harus mensintesis suara, menyeimbangkan latensi dan kualitas. Mode ini direkomendasikan untuk sebagian besar skenario. `commit`: Klien secara manual memicu sintesis. Mode ini memiliki latensi terendah, tetapi Anda harus mengelola integritas kalimat sendiri.
format	str	Tidak	Format output audio dari model. Format yang didukung: `pcm` (default) `wav` `mp3` `opus` Qwen-TTS-Realtime (lihat Model yang didukung) hanya mendukung `pcm`.
sample_rate	int	Tidak	Laju sampel output audio dari model, dalam Hz. Laju sampel yang didukung: 8000 16000 24000 (default) 48000 Qwen-TTS-Realtime (lihat Model yang didukung) hanya mendukung 24000.
speech_rate	float	Tidak	Laju bicara audio. Nilai 1.0 adalah kecepatan normal. Nilai kurang dari 1.0 lebih lambat, dan nilai lebih dari 1.0 lebih cepat. Nilai default: 1.0. Rentang valid: [0.5, 2.0]. Qwen-TTS-Realtime (lihat Model yang didukung) tidak mendukung parameter ini.
volume	int	Tidak	Volume audio. Nilai default: 50. Rentang valid: [0, 100]. Qwen-TTS-Realtime (lihat Model yang didukung) tidak mendukung parameter ini.
pitch_rate	float	Tidak	Pitch audio hasil sintesis. Nilai default: 1.0. Rentang valid: [0.5, 2.0]. Qwen-TTS-Realtime (lihat Model yang didukung) tidak mendukung parameter ini.
bit_rate	int	Tidak	Menentukan bitrate audio dalam kbps. Bitrate yang lebih tinggi menghasilkan kualitas audio lebih baik dan ukuran file lebih besar. Parameter ini hanya tersedia ketika format audio (`response_format`) diatur ke `opus`. Nilai default: 128. Rentang valid: [6, 510]. Qwen-TTS-Realtime (lihat Model yang didukung) tidak mendukung parameter ini.
instructions	str	Tidak	Menetapkan instruksi. Untuk informasi selengkapnya, lihat Real-time speech synthesis - Qwen. Nilai default: None. Parameter ini tidak aktif jika tidak diatur. Batas panjang: Panjang tidak boleh melebihi 1600 token. Bahasa yang didukung: Hanya Bahasa Tiongkok dan Inggris. Cakupan: Fitur ini hanya tersedia untuk seri model Qwen3-TTS-Instruct-Flash-Realtime.
optimize_instructions	bool	Tidak	Menentukan apakah akan mengoptimalkan `instructions` untuk meningkatkan naturalitas dan ekspresivitas sintesis suara. Nilai default: False Perilaku: Ketika diatur ke True, sistem meningkatkan dan menulis ulang `instructions` secara semantik untuk menghasilkan instruksi internal yang dioptimalkan untuk sintesis suara. Skenario: Direkomendasikan untuk skenario yang memerlukan ekspresi suara berkualitas tinggi dan detail halus. Ketergantungan: Parameter ini bergantung pada pengaturan parameter `instructions`. Jika `instructions` kosong, parameter ini tidak berpengaruh. Cakupan: Fitur ini hanya tersedia untuk seri model Qwen3-TTS-Instruct-Flash-Realtime.

Antarmuka utama

Kelas QwenTtsRealtime

Impor: from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime

Signature metode	Event respons server (dikirimkan melalui callback)	Deskripsi
`def connect(self) -> None`	session.created Sesi dibuat session.updated Konfigurasi sesi diperbarui	Terhubung ke server.
`def update_session(self, voice: str, response_format: AudioFormat = AudioFormat. PCM_24000HZ_MONO_16BIT, mode: str = 'server_commit', language_type : str = "Chinese", **kwargs) -> None`	session.updated Konfigurasi sesi diperbarui	Perbarui konfigurasi sesi default. Untuk detail parameter, lihat Parameter permintaan. Setelah terhubung, server mengembalikan konfigurasi input dan output default. Panggil metode ini segera setelah terhubung untuk memperbarui default tersebut. Server memvalidasi parameter saat menerima event session.update. Jika validasi gagal, server mengembalikan error; jika tidak, konfigurasi sesi diperbarui.
`def append_text(self, text: str) -> None`	Tidak ada	Tambahkan chunk teks ke buffer input cloud (penyimpanan sementara teks sebelum dikirim). Dalam mode server_commit, server menentukan kapan harus mengirim dan mensintesis teks dalam buffer. Dalam mode commit, klien harus memicu sintesis dengan memanggil commit.
`def clear_appended_text(self, ) -> None`	input_text_buffer.cleared Teks biasa diterima oleh server.	Hapus semua teks dalam buffer cloud.
`def commit(self, ) -> None`	input_text_buffer.committed Kirim teks dan picu sintesis suara response.output_item.added Konten output baru ditambahkan response.content_part.added Konten baru ditambahkan ke pesan asisten response.audio.delta Audio inkremental yang dihasilkan model response.audio.done Generasi audio selesai response.content_part.done Streaming konten audio untuk pesan asisten selesai response.output_item.done Streaming seluruh item output untuk pesan asisten selesai response.done Respons selesai	Kirim semua teks dalam buffer cloud dan langsung lakukan sintesis. Mengembalikan error jika buffer kosong. Dalam mode server_commit, klien tidak perlu mengirim event ini. Server secara otomatis mengirim buffer. Dalam mode commit, klien harus memanggil commit untuk memicu sintesis suara.
`def finish(self, ) -> None`	session.finished Respons selesai	Akhiri tugas.
`def close(self, ) -> None`	Tidak ada	Tutup koneksi.
`def get_session_id(self) -> str`	Tidak ada	Dapatkan ID sesi untuk tugas saat ini.
`def get_last_response_id(self) -> str`	Tidak ada	Dapatkan ID respons dari respons terbaru.
`def get_first_audio_delay(self)`	Tidak ada	Dapatkan penundaan sebelum paket audio pertama tiba.

Antarmuka callback (QwenTtsRealtimeCallback)

Server mengirim respons dan data melalui callback. Implementasikan metode callback untuk menanganinya.

Impor: from dashscope.audio.qwen_tts_realtime import QwenTtsRealtimeCallback

Metode	Parameter	Nilai kembalian	Deskripsi
`def on_open(self) -> None`	Tidak ada	Tidak ada	Dipanggil ketika koneksi server terbentuk.
`def on_event(self, message: str) -> None`	message: Event respons server.	Tidak ada	Mencakup respons panggilan API, teks yang dihasilkan model, dan audio. Lihat Event server.
`def on_close(self, close_status_code, close_msg) -> None`	close_status_code: Kode status penutupan WebSocket. close_msg: Pesan penutupan WebSocket.	Tidak ada	Dipanggil setelah server menutup koneksi.