Tous les produits
Search
Centre de documentation

Alibaba Cloud Model Studio:Python SDK

Dernière mise à jour :Nov 19, 2026

Cette rubrique présente les interfaces principales et les paramètres de requête pour appeler les modèles de la série Qwen-TTS-Realtime avec le SDK DashScope pour Python.

Prérequis

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

Démarrage rapide

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

# Les API Key diffèrent entre les régions de Singapour et de Pékin. Obtenez votre API Key : https://www.alibabacloud.com/help/model-studio/get-api-key
# Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Voici la configuration de la région de Singapour. Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Thread récepteur : itère les événements du serveur et écrit l'audio dans le fichier de façon incrémentale
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 ...')

    # Crée une session de synthèse vocale en temps réel : l'entrée dans le contexte with établit automatiquement la connexion
    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)
            # Notifie le serveur que la saisie est terminée (en mode server_commit, le serveur décide du moment de la synthèse)
            session.end_session()
            receiver.result()
        print('[Metric] session: {}, first audio delay: {}'.format(
            session.session_id,
            session.last_first_audio_delay,
        ))
import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor

import dashscope

text_to_synthesize = [
    'This is the first sentence.',
    'This is the second sentence.',
    'This is the third sentence.',
]

# Les API Key diffèrent entre les régions de Singapour et de Pékin. Obtenez votre API Key : https://www.alibabacloud.com/help/model-studio/get-api-key
# Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Voici la configuration de la région de Singapour. Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Thread récepteur : itère les événements du serveur et écrit l'audio dans le fichier de façon incrémentale
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 ...')

    # Crée une session de synthèse vocale en temps réel : l'entrée dans le contexte with établit automatiquement la connexion
    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='commit'
        )
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            for text in text_to_synthesize:
                print(f'send text: {text}')
                session.send_event({'type': 'input_text_buffer.append', 'text': text})
                # En mode commit, le client déclenche la synthèse
                session.send_event({'type': 'input_text_buffer.commit'})
                time.sleep(0.1)
            session.end_session()
            receiver.result()
        print('[Metric] session: {}, first audio delay: {}'.format(
            session.session_id,
            session.last_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 la méthode connect de client.audio.realtime :

Paramètre

Type

Obligatoire

Description

model

str

Oui

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

ws_url

str

Non

Endpoint de la session. S'il est omis, il est déduit automatiquement des paramètres de construction workspace/region du Client (Chine (Pékin) : wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime ; Singapour : wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime).

Configurez les paramètres suivants via la méthode update_session de la session (les paramètres nommés se transmettent directement, les autres sont transférés à l'objet session de l'événement session.update) :

ParamètreTypeObligatoireDescription

voice

str

Oui

Voix utilisée pour la synthèse vocale. Pour plus d'informations, voir Liste des voix Qwen-TTS.

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.

response_format

str

Non

Format de sortie audio du modèle.

Formats pris en charge :

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

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

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

volume

int

Non

Volume sonore de l'audio.

Plage valide : [0, 100].

pitch_rate

float

Non

Hauteur tonale de l'audio synthétisé.

Valeur par défaut : 1,0.

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

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

Référence de l’API

Session (RealtimeSession)

Une session de synthèse vocale en temps réel est créée via client.audio.realtime.connect(model=...). La connexion est établie automatiquement à l'entrée dans le contexte with (vous pouvez également appeler manuellement la méthode connect() de la session).

Signature de la méthode

Événements de réponse du serveur (transmis via l'itération de events())

Description

def connect(self) -> "RealtimeSession"

session.created

Session créée

session.updated

Configuration de session mise à jour

Établit la connexion au serveur. Appelée automatiquement à l'entrée dans le contexte with.

def update_session(self,
                   output_modalities: List[str],
                   *,
                   voice: str = None,
                   **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 send_event(self,
               event: Dict[str, Any]) -> None

None

Envoie un événement brut. La saisie de texte s'effectue via la famille d'événements input_text_buffer : ajout d'un segment de texte au tampon d'entrée cloud ({"type": "input_text_buffer.append", "text": ...}). Le tampon est un stockage temporaire du texte, écrit puis envoyé ultérieurement.

  • 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 envoyer l'événement input_text_buffer.commit pour déclencher la synthèse vocale.
def send_event(self,
               event: Dict[str, Any]) -> None

input_text_buffer.cleared

Efface le texte reçu par le serveur

Envoie l'événement {"type": "input_text_buffer.clear"} pour supprimer tout le texte du tampon cloud.

def send_event(self,
               event: Dict[str, Any]) -> 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

Envoie l'événement {"type": "input_text_buffer.commit"} pour soumettre l'intégralité du texte précédemment ajouté au tampon cloud et la synthétiser immédiatement. 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 déclencher la synthèse vocale via commit.
def end_session(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

Envoie l'événement session.finish pour terminer la tâche. Continuez ensuite à consommer events() jusqu'à l'événement session.finished.

def close(self, ) -> None

None

Ferme la connexion. Appelée automatiquement à la sortie du contexte with.

session.session_id

None

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

session.last_response_id

None

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

session.last_first_audio_delay

None

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

Itération d'événements (events())

Le serveur renvoie ses réponses et données sous forme d'événements. Itérez le events() de la session dans le thread récepteur pour traiter les événements du serveur ; l'itération se termine après l'événement session.finished. Les événements error sont levés sous forme d'exceptions DashScopeError, que vous pouvez capturer avec try/except.

Méthode

Paramètres

Valeur de retour

Description

def events(self) -> Iterator[Dict]

event : Événement de réponse du serveur (dict).

Itérateur

Comprend les réponses aux appels API, ainsi que le texte et l'audio générés par le modèle. L'itération se termine après l'événement session.finished. Pour plus d'informations, voir Événements serveur.

def recv_event(self) -> Optional[Dict]

event : Événement de réponse du serveur (dict).

Événement ou None

Lit un événement du serveur. Renvoie None après une fermeture normale.