Tous les produits
Search
Centre de documentation

Alibaba Cloud Model Studio:Python SDK

Dernière mise à jour :Oct 11, 2026

Cette rubrique présente les interfaces principales et les paramètres de requête pour appeler la synthèse vocale en temps réel (Qwen) avec le SDK DashScope pour Python.

Guide d'utilisation : Pour une présentation des modèles et des recommandations de sélection, consultez Synthèse vocale en temps réel – Qwen ou Synthèse vocale – Qwen.

Prérequis

SDK DashScope pour Python version 1.25.11 ou ultérieure requis.

Premiers pas

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.5-omni-plus-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.5-omni-plus-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(),
                    ))
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.5-omni-plus-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.5-omni-plus-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(),
                    ))

Consultez le dépôt GitHub pour télécharger d'autres exemples de code.

Paramètres de requête

Définissez ces paramètres dans le constructeur QwenTtsRealtime :

Paramètre

Type

Obligatoire

Description

model

str

Oui

Nom du modèle (voir Modèles pris en charge).

url

str

Oui

Chine (Pékin) : wss://dashscope.aliyuncs.com/api-ws/v1/realtime

Singapour : wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime

Configurez les paramètres suivants via update_session :

ParamètreTypeObligatoireDescription

voice

str

Oui

Voix utilisée pour la synthèse vocale. Pour plus d'informations, voir Voix prises en charge.

Les voix système et les voix personnalisées sont prises en charge :

  • Voix système : Disponibles uniquement pour les séries de modèles Qwen3-TTS-Instruct-Flash-Realtime, Qwen3-TTS-Flash-Realtime et Qwen-TTS-Realtime. Pour écouter des échantillons, voir Voix prises en charge.

  • Voix personnalisées
    • Voix créées via la fonctionnalité Clonage vocal (Qwen) : Disponibles uniquement pour la série de modèles Qwen3-TTS-VC-Realtime.
    • Voix créées via la fonctionnalité Conception vocale (Qwen) : Disponibles uniquement pour la série de modèles Qwen3-TTS-VD-Realtime.

language_type

str

Non

Spécifie la langue de l'audio synthétisé. La valeur par défaut est Auto.

  • Auto : À utiliser lorsque la langue du texte est incertaine ou mixte. Le modèle adapte automatiquement la prononciation aux différents segments linguistiques, sans toutefois garantir une précision absolue.

  • Langue spécifique : Recommandée pour les textes monolingues. Spécifier la langue améliore considérablement la qualité de la synthèse et donne généralement de meilleurs résultats que le mode Auto. Les valeurs valides sont les suivantes :

    • Chinese
    • English
    • German
    • Italian
    • Portuguese
    • Spanish
    • Japanese
    • Korean
    • French
    • Russian

mode

str

Non

Mode d'interaction. Valeurs valides :

  • server_commit (par défaut) : Le serveur détermine automatiquement le moment opportun pour synthétiser la parole, ce qui permet d'équilibrer latence et qualité. Ce mode est recommandé pour la plupart des cas d'usage.
  • commit : Le client déclenche manuellement la synthèse. Bien qu'il offre la latence la plus faible, ce mode exige que vous gériez vous-même l'intégrité des phrases.

format

str

Non

Format de sortie audio du modèle.

Formats pris en charge :

  • pcm (par défaut)
  • wav
  • mp3
  • opus

Qwen-TTS-Realtime (voir Modèles pris en charge) prend uniquement en charge le format pcm.

sample_rate

int

Non

Fréquence d'échantillonnage de la sortie audio du modèle, exprimée en Hz.

Fréquences d'échantillonnage disponibles :

  • 8000
  • 16000
  • 24000 (par défaut)
  • 48000

Qwen-TTS-Realtime (voir Modèles pris en charge) prend uniquement en charge la fréquence 24000.

speech_rate

float

Non

Vitesse de lecture de l'audio. Une valeur de 1,0 correspond à la vitesse normale. Une valeur inférieure à 1,0 ralentit la lecture, tandis qu'une valeur supérieure l'accélère.

Valeur par défaut : 1,0.

Plage valide : [0,5, 2,0].

Qwen-TTS-Realtime (voir Modèles pris en charge) ne prend pas en charge ce paramètre.

volume

int

Non

Volume sonore de l'audio.

Valeur par défaut : 50.

Plage valide : [0, 100].

Qwen-TTS-Realtime (voir Modèles pris en charge) ne prend pas en charge ce paramètre.

pitch_rate

float

Non

Hauteur tonale de l'audio synthétisé.

Valeur par défaut : 1,0.

Plage valide : [0,5, 2,0].

Qwen-TTS-Realtime (voir Modèles pris en charge) ne prend pas en charge ce paramètre.

bit_rate

int

Non

Définit le débit binaire audio en kbps. Un débit plus élevé améliore la qualité audio mais augmente la taille du fichier. Ce paramètre n'est disponible que si le format audio (response_format) est défini sur opus.

Valeur par défaut : 128.

Plage valide : [6, 510].

Qwen-TTS-Realtime (voir Modèles pris en charge) ne prend pas en charge ce paramètre.

instructions

str

Non

Définit les instructions. Pour plus d'informations, voir Synthèse vocale en temps réel - Qwen.

Valeur par défaut : None. Le paramètre est inactif s'il n'est pas défini.

Limite de longueur : 1600 tokens maximum.

Langues prises en charge : Chinois et anglais uniquement.

Champ d'application : Cette fonctionnalité est réservée à la série de modèles Qwen3-TTS-Instruct-Flash-Realtime.

optimize_instructions

bool

Non

Indique s'il faut optimiser les instructions afin d'améliorer le naturel et l'expressivité de la synthèse vocale.

Valeur par défaut : False

Comportement : Si cette option est activée (True), le système enrichit et reformule sémantiquement les instructions pour générer des directives internes optimisées pour la synthèse vocale.

Cas d'usage : Recommandé pour les scénarios nécessitant une expression vocale fine et de haute qualité.

Dépendance : Ce paramètre dépend du paramètre instructions. Si instructions est vide, ce paramètre reste sans effet.

Champ d'application : Cette fonctionnalité est réservée à la série de modèles Qwen3-TTS-Instruct-Flash-Realtime.

Interfaces principales

Classe QwenTtsRealtime

Importation : from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime

Signature de la méthode

Événements de réponse du serveur (via callback)

Description

def connect(self) -> None

session.created

Session créée

session.updated

Configuration de session mise à jour

Établit la connexion au serveur.

    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

Configuration de session mise à jour

Met à jour les configurations de session par défaut. Pour plus de détails sur les paramètres, reportez-vous à la section Paramètres de requête.

Une fois connecté, le serveur renvoie les configurations d'entrée et de sortie par défaut. Appelez cette méthode immédiatement après la connexion pour modifier ces valeurs par défaut.

Le serveur valide les paramètres lors de la réception d'un événement session.update. En cas d'échec de validation, il renvoie une erreur ; sinon, il applique la nouvelle configuration de session.

def append_text(self, text: str) -> None

None

Ajoute un segment de texte au tampon d'entrée cloud (stockage temporaire avant soumission).

  • En mode server_commit, le serveur décide du moment où soumettre et synthétiser le texte présent dans le tampon.
  • En mode commit, le client doit déclencher la synthèse en appelant commit.
def clear_appended_text(self, ) -> None

input_text_buffer.cleared

Efface le texte reçu par le serveur

Supprime tout le texte stocké dans le tampon cloud.

def commit(self, ) -> None

input_text_buffer.committed

Soumet le texte et déclenche la synthèse vocale

response.output_item.added

Nouvel élément de sortie ajouté

response.content_part.added

Nouveau contenu ajouté au message de l'assistant

response.audio.delta

Audio incrémentiel généré par le modèle

response.audio.done

Génération audio terminée

response.content_part.done

Streaming du contenu audio pour le message de l'assistant terminé

response.output_item.done

Streaming complet de l'élément de sortie pour le message de l'assistant terminé

response.done

Réponse terminée

Soumet l'intégralité du texte présent dans le tampon cloud et lance immédiatement la synthèse. Renvoie une erreur si le tampon est vide.

  • En mode server_commit, les clients n'ont pas besoin d'envoyer cet événement. Le serveur soumet automatiquement le contenu du tampon.
  • En mode commit, les clients doivent appeler commit pour déclencher la synthèse vocale.
def finish(self, ) -> None

session.finished

Réponse terminée

Termine la tâche en cours.

def close(self, ) -> None

None

Ferme la connexion.

def get_session_id(self) -> str

None

Récupère l'ID de session de la tâche actuelle.

def get_last_response_id(self) -> str

None

Récupère l'ID de la réponse la plus récente.

def get_first_audio_delay(self)

None

Récupère le délai écoulé avant l'arrivée du premier paquet audio.

Interface de callback (QwenTtsRealtimeCallback)

Le serveur transmet ses réponses et données via des callbacks. Implémentez les méthodes de callback appropriées pour les traiter.

Importation : from dashscope.audio.qwen_tts_realtime import QwenTtsRealtimeCallback

Méthode

Paramètres

Valeur de retour

Description

def on_open(self) -> None

None

None

Appelée lors de l'établissement de la connexion au serveur.

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

message : Événement de réponse du serveur.

None

Comprend les réponses aux appels API, ainsi que le texte et l'audio générés par le modèle. Voir Événements serveur.

def on_close(self, close_status_code, close_msg) -> None

close_status_code : Code de statut de fermeture WebSocket.

close_msg : Message de fermeture WebSocket.

None

Appelée après la fermeture de la connexion par le serveur.