Skip to main content

Qwen-Audio-TTS Python SDK

Intégrez la synthèse vocale en temps réel Qwen-Audio-TTS à votre application via le SDK Python DashScope, en utilisant les modes non diffusés (non-streaming), unidirectionnel ou bidirectionnel.

Consultez la documentation Qwen-Audio-TTS Python SDK actuelle.

Endpoint du service

L'endpoint du service du SDK est déterminé par les paramètres workspace/region du constructeur de Client (ils correspondent aux adresses ci-dessous, qui incluent le WorkspaceId). Pour basculer vers une autre région, modifiez les paramètres du constructeur de Client avec les valeurs de la région de destination.
  • Singapore
  • China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceRemplacez {WorkspaceId} par votre véritable ID d'espace de travail.
Alibaba Cloud Model Studio a publié des domaines spécifiques aux espaces de travail pour les régions Chine (Pékin) et Singapour. Ces nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • Chine (Pékin) : passez de dashscope.aliyuncs.com à {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : passez de dashscope-intl.aliyuncs.com à {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Ressource principale (client.audio.tts)

Chemin de la ressource : client.audio.tts Fonction : Synthèse vocale basée sur WebSocket, proposant trois formes d'appel : synthèse en un seul appel (synthesize), synthèse en flux (stream) et session de diffusion bidirectionnelle (connect).

Point d'entrée d'appel

# Synthèse en un seul appel : renvoie l'ensemble des octets audio
audio = client.audio.tts.synthesize(
    text,                      # text est obligatoire (argument positionnel)
    model="qwen-audio-3.0-tts-flash", # le modèle auquel appartient la voix
    voice="longanhuan_v3.6",   # la voix
    format="mp3",              # Format d'encodage audio, valeur par défaut "mp3"
    sample_rate=22050,         # Taux d'échantillonnage, valeur par défaut 22050
)

# Synthèse en flux : délivre les octets audio chunk par chunk (écrivez/lisez pendant la réception)
for chunk in client.audio.tts.stream(text, model=..., voice=...):
    ...

# Session de diffusion bidirectionnelle : envoyez le texte par segments ; la connexion est établie automatiquement à l'entrée dans le contexte with
with client.audio.tts.connect(model=..., voice=...) as session:
    session.send_text(text)    # Peut être appelée plusieurs fois pour ajouter du texte
    session.stop()             # Notifie le serveur que la saisie est terminée
    for chunk in session.audio_chunks():
        ...

synthesize() - sans streaming

Signature de la méthode :
def synthesize(self, text: str, *, model: str,
               voice: str, format: str = "mp3",
               sample_rate: int = 22050, volume: int = None,
               rate: float = None, pitch: float = None,
               language_hints: list = None, enable_ssml: bool = None,
               parameters: Dict = None, ...) -> bytes
Paramètres :
ParamètreTypeRequisDescription
textstrOuiLe texte complet à synthétiser. Longueur maximale: 20 000 caractères.
Valeur de retour : bytes contenant l'ensemble des données audio. Description : Cet appel bloquant attend et renvoie l'intégralité des données audio en une seule fois. Il convient particulièrement aux textes courts n'exigeant pas de performance temps réel stricte. Chaque appel à synthesize ou stream crée sa propre session ; il n'est pas nécessaire de réutiliser les instances.

stream() - streaming

Signature de la méthode :
def stream(self, text: str, *, model: str, voice: str,
           format: str = "mp3", sample_rate: int = 22050, ...) -> Iterator[bytes]
Paramètres :
ParamètreTypeRequisDescription
textstrOuiLe texte complet à synthétiser. Longueur maximale: 20 000 caractères.
Valeur de retour : Iterator[bytes], les données audio délivrées chunk par chunk. Description : Synthèse en flux qui envoie l'intégralité du texte en une fois et délivre l'audio chunk par chunk (Iterator[bytes]). Elle convient particulièrement aux scénarios de synthèse vocale de textes courts exigeant une forte réactivité temps réel. Pour envoyer le texte par segments, utilisez la session de diffusion bidirectionnelle (connect).

send_text() - saisie en flux (méthode de session)

Envoie le texte par segments dans une session de diffusion bidirectionnelle (client.audio.tts.connect(...)). Signature de la méthode :
def send_text(self, text: str) -> None
Paramètres : text est le segment de texte à synthétiser en cours. Appelez send_text plusieurs fois pour ajouter du texte. Maximum par appel: 20 000 caractères ; maximum cumulé: 200 000 caractères. L'envoi de texte et la réception d'audio doivent s'exécuter de manière concurrente (à utiliser avec audio_chunks()/events() et stop).

stop() - terminer la saisie en flux (méthode de session)

Signature de la méthode :
def stop(self) -> None
Description : Notifie au serveur que tout le texte a été envoyé. Cet appel ne bloque pas le thread courant ; le thread de réception doit continuer à consommer audio_chunks()/events() jusqu'à ce que le texte restant soit synthétisé et que toutes les données audio soient renvoyées. Si cette méthode n'est pas appelée, il est possible que le dernier texte ne soit pas converti en parole.

cancel() - annuler la synthèse en flux (méthode de session)

Signature de la méthode :
def cancel(self) -> None
Description : Annule le tour courant de synthèse vocale en flux. Après cet appel, le SDK met immédiatement fin à la tâche courante. Une fois annulée, la session ne peut plus envoyer de texte ; créez une nouvelle session pour poursuivre la synthèse.

Métriques et réponses de la session (attributs de session)

session.first_package_delay
session.usage
session.last_response
  • first_package_delay : float, la latence en millisecondes entre l'envoi du texte et la réception du premier chunk audio. À lire après la fin de la synthèse.
  • usage : dict, les informations d'utilisation de la tâche de synthèse la plus récente.
  • last_response : dict, le message de réponse de la tâche de synthèse la plus récente (avec les clés header/payload). Le request_id de la requête la plus récente peut être obtenu depuis le header de session.last_response, utile pour le dépannage et la corrélation de logs.

Paramètres de requête

Les paramètres suivants se configurent via les méthodes synthesize/stream/connect de client.audio.tts pour contrôler le modèle, la voix, le format et les caractéristiques audio (model, voice, format, sample_rate, volume, rate, pitch, language_hints et enable_ssml sont des paramètres nommés ; les autres paramètres se transmettent via le dictionnaire parameters).
ParamètreTypeRequisDescription
modelstrOuiLe nom du modèle.
voicestrOuiLa voix utilisée pour la synthèse vocale.
  • Voix système : consultez la liste des voix de Qwen-Audio-TTS
  • Voix clonées : voix personnalisées créées par clonage vocal
  • Voix personnalisées : voix personnalisées créées par voice design
formatstrNonFormat d'encodage audio.Valeur par défaut : mp3.Prend en charge mp3, wav, pcm et d'autres formats. Le taux d'échantillonnage se définit via le paramètre sample_rate, avec une valeur par défaut de 22050.
volumeintNonLe niveau de volume.Valeur par défaut : 50.Valeurs valides : [0, 100].
ratefloatNonLa vitesse de la parole.Valeur par défaut : 1.0.Valeurs valides : [0.5, 2.0].
pitchfloatNonLe ton.Valeur par défaut : 1.0.Valeurs valides : [0.5, 2.0].
bit_rateintNonLe débit binaire audio en kbps. Lorsque le format audio est mp3 ou opus, utilisez bit_rate pour ajuster le débit.Valeur par défaut : 32.Valeurs valides : [6, 510].Configurez bit_rate via le dictionnaire parameters :
audio = client.audio.tts.synthesize(
    "Text to synthesize",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    parameters={"bit_rate": 128},
)
word_timestamp_enabledboolNonIndique s'il faut activer les horodatages au niveau du mot.Valeur par défaut : false.Disponible uniquement en mode de sortie en flux. Les voix clonées sont prises en charge. Pour les voix système compatibles, consultez la liste des voix de Qwen-Audio-TTS.Configurez word_timestamp_enabled via le dictionnaire parameters :
audio = client.audio.tts.stream(
    "Text to synthesize",
    model="qwen-audio-3.0-tts-flash",
    voice="your_voice",  # A system or cloned voice that supports word-level timestamps
    parameters={"word_timestamp_enabled": True},
)
seedintNonUne graine aléatoire pour contrôler la variation de la sortie de synthèse. Lorsque la version du modèle, le texte, la voix et les autres paramètres ne changent pas, l'utilisation de la même graine produit des résultats identiques.Valeur par défaut : 0.Valeurs valides : [0, 65535].
language_hintslist[str]Non
Pour les voix multilingues et dialectales de qwen-audio-3.1-tts-flash, ce paramètre permet de spécifier la langue ou le dialecte. Consultez les paramètres des voix multilingues et dialectales pour en savoir plus.
Spécifie la langue cible de la synthèse vocale afin d'améliorer la qualité de sortie.Lorsque la prononciation des chiffres, le développement des abréviations, la lecture des symboles ou la synthèse en langues minoritaires ne répondent pas aux attentes, utilisez ce paramètre. Par exemple :
  • Prononciation inattendue des chiffres : « bonjour, ceci est 110 » est lu « bonjour, ceci est un zéro » au lieu de la prononciation attendue
  • Mauvaise lecture des symboles : « @ » est lu avec son équivalent dans une autre langue au lieu d'« arobase »
  • Qualité de synthèse médiocre en langues minoritaires, avec des résultats peu naturels
  • zh : Chinois
  • en : Anglais
  • fr : Français
  • de : Allemand
  • ja : Japonais
  • ko : Coréen
  • ru : Russe
  • pt : Portugais
  • th : Thaï
  • id : Indonésien
  • vi : Vietnamien
  • es : Espagnol
  • it : Italien
  • ms : Malais
  • fil : Philippin
  • ar : Arabe
  • other: Autres langues (prises en charge par qwen-audio-3.1-tts-flash) bulgare, néerlandais, hongrois, roumain, danois, croate, grec, tchèque, norvégien, suédois, hindi, slovaque, finnois, ourdou, serbe, espagnol du Mexique, lituanien, letton, turc, persan, hébreu, mongol, slovène, azerbaïdjanais, polonais, catalan, khmer, portugais brésilien, lao, géorgien, afrikaans, népalais, biélorusse, malayalam, luxembourgeois, albanais, tamoul, cingalais, télougou, estonien, cebuano, bosniaque, birman, arménien, latin, islandais, maltais, swahili, kazakh, créole seychellois, ukrainien.
  • Ce paramètre est un tableau, mais la version actuelle ne traite que le premier élément. Passez une valeur unique.
  • Ce paramètre spécifie la langue cible de la synthèse vocale. Il n'est pas lié à la langue de l'échantillon audio utilisé pour le clonage vocal. Pour définir la langue source d'une tâche de clonage, consultez la référence de l'API de clonage vocal.
instructionstrNonContrôle les caractéristiques de la synthèse, telles que le dialecte, l'émotion ou le style de parole.Pour les détails d'utilisation, consultez Contrôle par instructions.
enable_aigc_tagboolNonIndique s'il faut intégrer un filigrane AIGC dans l'audio généré. Lorsque la valeur est true, le filigrane est intégré dans les fichiers audio aux formats compatibles (wav/mp3/opus).Valeur par défaut : false.Configurez enable_aigc_tag, aigc_propagator et aigc_propagate_id via le dictionnaire parameters :
audio = client.audio.tts.synthesize(
    "Text to synthesize",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    parameters={
        "enable_aigc_tag": True,
        "aigc_propagator": "your_propagator",
        "aigc_propagate_id": "your_propagate_id"
    },
)
aigc_propagatorstrNonDéfinit le champ ContentPropagator du filigrane AIGC, identifiant le propagateur du contenu. Ne prend effet que si enable_aigc_tag vaut true.Valeur par défaut : l'UID Alibaba Cloud.Se configure via le dictionnaire parameters. Voir l'exemple de enable_aigc_tag.
aigc_propagate_idstrNonDéfinit le champ PropagateID du filigrane AIGC, identifiant de manière unique une action de propagation donnée. Ne prend effet que si enable_aigc_tag vaut true.Valeur par défaut : l'ID de requête de la requête de synthèse vocale en cours.Se configure via le dictionnaire parameters. Voir l'exemple de enable_aigc_tag.
hot_fixdictNonConfigure des corrections de prononciation et des remplacements de texte appliqués avant la synthèse.Paramètres :
  • pronunciation : prononciation personnalisée. Spécifie des annotations pinyin pour des mots afin de corriger des prononciations par défaut inexactes.
  • replace : remplacement de texte. Remplace des mots spécifiques par un texte cible avant la synthèse. Le texte remplacé sert d'entrée réelle de la synthèse.
Exemple :
audio = client.audio.tts.synthesize(
    "Text to synthesize",
    model="qwen-audio-3.0-tts-flash",
    voice="your_voice_id", # Voice
    parameters={
        "hot_fix": {
            "pronunciation": [{"weather": "tian1 qi4"}],
            "replace": [{"today": "gold day"}]
        }
    },
)

Itération de session et événements

La synthèse en flux n'utilise plus d'interfaces de callback : l'audio et les événements du serveur se reçoivent via les méthodes d'itération de la session. stream()/synthesize() ne nécessitent aucune gestion de session ; le cycle de vie d'une session de diffusion bidirectionnelle (client.audio.tts.connect(...)) est : entrée dans le contexte with qui établit automatiquement la connexion → appels multiples à send_text() → stop() → lecture de tous les résultats → sortie du contexte qui ferme automatiquement la connexion.

audio_chunks() - itérer les données audio

Signature de la méthode :
def audio_chunks(self) -> Iterator[bytes]
Valeur de retour : Iterator[bytes], les données binaires audio délivrées chunk par chunk, dans le format spécifié par le paramètre format. Description : Itérez dans le thread de réception pour recevoir les données audio chunk par chunk ; pendant la synthèse, plusieurs chunks sont délivrés. Écrivez les données dans un fichier ou envoyez-les à un dispositif de lecture. Une session n'autorise qu'un seul lecteur de events() ou audio_chunks().

events() - itérer les événements du serveur

Signature de la méthode :
def events(self) -> Generator[Union[Dict, bytes], None, None]
Valeur de retour : Renvoie à la fois des événements de réponse du serveur (dict, contenant header (informations de la requête) et payload (informations de sortie)) et des bytes audio. Le champ payload.output contient le type d'événement, le texte original et d'autres informations. Consultez champ output dans les messages de events(). Description : Itérez sur les réponses du serveur dans le thread de réception. Les réponses contiennent les informations de sortie des événements de synthèse (type d'événement, texte original, informations de phrase, etc.) ; accédez directement à payload.output pour plus de détails.

Gestion des erreurs

Lorsqu'une erreur survient pendant la synthèse, la couche WebSocket lève une exception DashScopeError et la connexion se ferme automatiquement après la levée de l'exception. Utilisez try/except côté envoi/réception pour capturer et consigner les erreurs à des fins de dépannage :
from dashscope.v2 import DashScopeError

try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)

Cycle de vie de la session

  • La connexion est établie automatiquement à l'entrée dans le contexte with (vous pouvez initialiser des flux de sortie audio ou ouvrir des ressources fichier en amont).
  • Une fois tout le texte synthétisé et toutes les données audio délivrées, l'itération de events()/audio_chunks() se termine ; vous pouvez ensuite lire des métriques de performance comme first_package_delay.
  • La connexion se ferme automatiquement à la sortie du contexte with (vous pouvez ensuite libérer les dispositifs de lecture audio et d'autres ressources).

Champ output dans les messages de events()

Le dict d'événement délivré par l'itérateur events() de la session contient un champ payload.output avec les informations de l'événement de synthèse. Utilisez ce champ pour suivre la progression de la synthèse et récupérer les détails par phrase. La structure du champ output est la suivante :
ChampTypeDescription
typestrType d'événement. Valeurs: sentence-begin (début de synthèse de phrase), sentence-synthesis (synthèse de phrase en cours) ou sentence-end (fin de synthèse de phrase).
original_textstrLe texte original de la phrase en cours. Renvoyé dans les événements sentence-begin et sentence-end.
sentencedictInformations de la phrase. Contient index (numéro de séquence de la phrase) et words (liste de mots avec informations d'horodatage lorsque word_timestamp_enabled est activé).
Exemple de message :
{
  "header": {
    "task_id": "xxx",
    "event": "result-generated",
    "attributes": {}
  },
  "payload": {
    "output": {
      "type": "sentence-begin",
      "original_text": "How is the weather today?",
      "sentence": {
        "index": 0,
        "words": []
      }
    }
  }
}
Exemple d'analyse :
def handle_event(event):
    output = (event.get('payload') or {}).get('output') or {}
    event_type = output.get('type', '')
    original_text = output.get('original_text', '')
    if event_type:
        print(f'Event type: {event_type}, original text: {original_text}')

Exemples de code

Le SDK prend en charge les modes de synthèse suivants :
  • Sans streaming : appel bloquant qui envoie l'intégralité du texte en une fois et renvoie directement l'audio complet. Idéal pour la synthèse vocale de textes courts.
  • Streaming unidirectionnel : appel non bloquant qui envoie l'intégralité du texte en une fois et reçoit les données en itérant sur les chunks audio délivrés par stream. Idéal pour la synthèse vocale de textes courts exigeant une forte réactivité temps réel.
  • Streaming bidirectionnel : appel non bloquant qui envoie le texte en plusieurs segments et reçoit en temps réel le flux audio synthétisé de manière incrémentale en itérant sur les méthodes audio_chunks()/events() de la session. Idéal pour la synthèse vocale de textes longs exigeant une forte réactivité temps réel.
  • Sans streaming
  • Streaming unidirectionnel
  • Streaming bidirectionnel
Le texte envoyé en un seul appel ne doit pas dépasser 20 000 caractères. Dépasser cette limite déclenche une erreur.
Chaque appel à synthesize ou stream crée sa propre session ; il n'est pas nécessaire de réutiliser les instances.
# coding=utf-8

import os

import dashscope

# Les API Key des régions Singapour et Pékin sont différentes. 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"
# 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.
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Modèle
model = "qwen-audio-3.0-tts-flash"
# Voix
voice = "longanhuan_v3.6"

# Envoyez le texte à synthétiser et récupérez l'audio binaire
audio = client.audio.tts.synthesize("How is the weather today?", model=model, voice=voice)

# Enregistrez l'audio dans un fichier local
with open('output.mp3', 'wb') as f:
    f.write(audio)
  • CLI dashscope
Appel via la ligne de commande dashscope.
export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, ap-southeast-1 with your region (e.g., us-east-1, eu-central-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
dashscope speech-synthesis create -m qwen-audio-3.0-tts-flash -t "Hello world" --voice longanhuan_v3.6
L'assistant interactif SDK Expert permet d'effectuer les mêmes tâches de développement et de dépannage en langage naturel ; consultez DashScope SDK Expert.
Pour le tableau complet des régions, consultez Présentation des URL de base.