Skip to main content

Python SDK

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,
        ))
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
voicestrOuiVoix utilisée pour la synthèse vocale. Pour plus d'informations, voir Liste des voix Qwen-TTS.
language_typestrNonSpé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
modestrNonMode 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_formatstrNonFormat de sortie audio du modèle.Formats pris en charge :
  • pcm (par défaut)
  • wav
  • mp3
  • opus
sample_rateintNonFré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_ratefloatNonVitesse 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].
volumeintNonVolume sonore de l'audio.Plage valide : [0, 100].
pitch_ratefloatNonHauteur tonale de l'audio synthétisé.Valeur par défaut : 1,0.Plage valide : [0,5, 2,0].
bit_rateintNonDé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
NoneEnvoie 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
NoneFerme la connexion. Appelée automatiquement à la sortie du contexte with.
session.session_id
NoneRécupère l'ID de session de la tâche actuelle.
session.last_response_id
NoneRécupère l'ID de la réponse la plus récente.
session.last_first_audio_delay
NoneRé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éthodeParamètresValeur de retourDescription
def events(self) -> Iterator[Dict]
event : Événement de réponse du serveur (dict).ItérateurComprend 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 NoneLit un événement du serveur. Renvoie None après une fermeture normale.