Skip to main content

Python SDK

Topik ini menjelaskan antarmuka utama dan parameter permintaan untuk memanggil model seri Qwen-TTS-Realtime menggunakan DashScope Python SDK.

Prasyarat

Versi DashScope Python SDK harus 2.0.1 atau lebih baru.

Mulai cepat

import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor

import dashscope

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!'
]

# Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/model-studio/get-api-key
# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Berikut adalah konfigurasi untuk wilayah Singapura (ap-southeast-1). Saat memanggil, ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Konfigurasi berbeda-beda untuk setiap wilayah.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Thread penerima: iterasi event server dan tulis audio ke file secara bertahap
def receive_events(session):
    with open('result_24k.pcm', 'wb') as f:
        for event in session.events():
            event_type = event.get('type')
            if event_type == 'session.created':
                print('start session: {}'.format(event['session']['id']))
            elif event_type == 'response.audio.delta':
                f.write(base64.b64decode(event['delta']))
            elif event_type == 'response.done':
                print(f'response {session.last_response_id} done')
            elif event_type == 'session.finished':
                print('session finished')

if __name__  == '__main__':
    print('Initializing ...')

    # Buat sesi sintesis ucapan real-time: memasuki konteks with akan otomatis membentuk koneksi
    with client.audio.realtime.connect(
            model='qwen3-tts-flash-realtime',
    ) as session:
        session.update_session(
            output_modalities=['audio'],
            voice='Cherry',
            response_format='pcm',
            sample_rate=24000,
            mode='server_commit'
        )
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            for text_chunk in text_to_synthesize:
                print(f'send text: {text_chunk}')
                session.send_event({'type': 'input_text_buffer.append', 'text': text_chunk})
                time.sleep(0.1)
            # Beri tahu server bahwa input telah selesai (dalam mode server_commit, server menentukan kapan sintesis dilakukan)
            session.end_session()
            receiver.result()
        print('[Metric] session: {}, first audio delay: {}'.format(
            session.session_id,
            session.last_first_audio_delay,
        ))
Kunjungi GitHub untuk mengunduh contoh kode tambahan.

Parameter permintaan

Parameter permintaan berikut dapat diatur melalui metode connect pada client.audio.realtime.

Parameter

Type

Wajib

Deskripsi

model

str

Ya

Nama model (lihat Model yang didukung).

ws_url

str

Tidak

Endpoint sesi. Jika tidak diatur, akan otomatis ditentukan oleh parameter konstruktor workspace/region dari Client (China (Beijing): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime; Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime).

Parameter permintaan berikut dapat dikonfigurasi melalui metode update_session pada sesi (parameter bernama diteruskan langsung, dan parameter lainnya diteruskan ke objek session pada event session.update).

Parameter

Type

Wajib

Deskripsi

voice

str

Ya

Voice untuk sintesis suara. Untuk informasi selengkapnya, lihat Daftar voice Qwen-TTS.

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.

response_format

str

Tidak

Format output audio dari model.

Format yang didukung:

  • pcm (default)

  • wav

  • mp3

  • opus

sample_rate

int

Tidak

Laju sampel output audio dari model, dalam Hz.

Laju sampel yang didukung:

  • 8000

  • 16000

  • 24000 (default)

  • 48000

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].

volume

int

Tidak

Volume audio.

Rentang valid: [0, 100].

pitch_rate

float

Tidak

Pitch audio hasil sintesis.

Nilai default: 1.0.

Rentang valid: [0.5, 2.0].

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].

Referensi API

Sesi (RealtimeSession)

Sesi sintesis ucapan real-time dibuat melalui client.audio.realtime.connect(model=...); memasuki konteks with akan otomatis membentuk koneksi (Anda juga dapat memanggil metode connect() pada sesi untuk membentuknya secara manual).
Signature metodeEvent respons server (dikirimkan melalui iterasi events())Deskripsi
def connect(self) -> "RealtimeSession"
session.created
Sesi dibuat
session.updated
Konfigurasi sesi diperbarui
Membentuk koneksi dengan server. Dipanggil otomatis saat memasuki konteks with.
def update_session(self,
                   output_modalities: List[str],
                   *,
                   voice: str = None,
                   **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 send_event(self,
               event: Dict[str, Any]) -> None
Tidak adaMengirim event mentah. Input teks diselesaikan melalui rangkaian event input_text_buffer: potongan teks ditambahkan ke buffer teks input di cloud ({"type": "input_text_buffer.append", "text": ...}). Buffer adalah penyimpanan sementara yang dapat Anda tulis dan kemudian dikirim.
  • Dalam mode "server_commit", server menentukan kapan teks dalam buffer dikirim dan disintesis.
  • Dalam mode "commit", klien harus secara aktif mengirim event input_text_buffer.commit untuk memicu sintesis ucapan.
def send_event(self,
               event: Dict[str, Any]) -> None
input_text_buffer.cleared
Mengosongkan teks yang diterima server
Mengirim event {"type": "input_text_buffer.clear"} untuk menghapus teks dalam buffer cloud saat ini.
def send_event(self,
               event: Dict[str, Any]) -> 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 end_session(self) -> None
session.finished
Respons selesai
Mengirim event session.finish untuk mengakhiri tugas. Setelah itu, terus konsumsi events() hingga event session.finished.
def close(self, ) -> None
Tidak adaMenutup koneksi. Dipanggil otomatis saat keluar dari konteks with.
session.session_id
Tidak adaDapatkan ID sesi untuk tugas saat ini.
session.last_response_id
Tidak adaDapatkan ID respons dari respons terbaru.
session.last_first_audio_delay
Tidak adaDapatkan penundaan sebelum paket audio pertama tiba.

Iterasi event (events())

Server mengembalikan event respons dan data kepada klien dalam bentuk event. Iterasikan events() sesi di thread penerima untuk memproses event server; iterasi berakhir setelah event session.finished; event error akan dilempar sebagai pengecualian DashScopeError dan dapat ditangkap menggunakan try/except.
MetodeParameterNilai kembalianDeskripsi
def events(self) -> Iterator[Dict]
event: Event respons server (dict).IteratorMencakup respons panggilan antarmuka serta teks dan audio yang dihasilkan model; iterasi berakhir setelah event session.finished. Untuk detailnya, lihat Event server
def recv_event(self) -> Optional[Dict]
event: Event respons server (dict).Event atau NoneMembaca satu event server; mengembalikan None setelah penutupan normal.