Prérequis
Qwen-Audio-TTS
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.CosyVoice
Endpoint du service
L'endpoint du SDK est déterminé par les paramètres workspace et 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 concernée.
- Singapore
- China (Beijing)
- CLI dashscope
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceRemplacez {WorkspaceId} par votre véritable ID d'espace de travail.Démarrage rapide
Qwen-Audio-TTS / CosyVoice
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.
- CLI dashscope
Appel via la ligne de commande dashscope.Pour le tableau complet des régions, consultez Présentation des URL de base.
CosyVoice
Le SDK fournit les interfaces clés de la synthèse vocale et prend en charge les modes d'appel 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 exception
DashScopeError.Dans les exemples de code communs, choisissez le même mode d’appel. Définissez model sur cosyvoice-v3-plus et voice sur longanyang.Paramètres de requête
Qwen-Audio-TTS
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ètre | Type | Requis | Description |
|---|---|---|---|
model | str | Oui | Le nom du modèle. |
voice | str | Oui | La voix utilisée pour la synthèse vocale.
|
format | str | Non | Format 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. |
volume | int | Non | Le niveau de volume.Valeur par défaut : 50.Valeurs valides : [0, 100]. |
rate | float | Non | La vitesse de la parole.Valeur par défaut : 1.0.Valeurs valides : [0.5, 2.0]. |
pitch | float | Non | Le ton.Valeur par défaut : 1.0.Valeurs valides : [0.5, 2.0]. |
bit_rate | int | Non | Le 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 : |
word_timestamp_enabled | bool | Non | Indique 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 : |
seed | int | Non | Une 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_hints | list[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.
Valeurs valides
|
instruction | str | Non | Contrô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_tag | bool | Non | Indique 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 : |
aigc_propagator | str | Non | Dé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_id | str | Non | Dé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_fix | dict | Non | Configure des corrections de prononciation et des remplacements de texte appliqués avant la synthèse.Paramètres :
|
CosyVoice
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ètre | Type | Requis | Description |
|---|---|---|---|
model | str | Oui | Le nom du modèle. |
voice | str | Oui | La voix utilisée pour la synthèse vocale.
|
format | str | Non | Format 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. |
volume | int | Non | Le niveau de volume.Valeur par défaut : 50.Valeurs valides : [0, 100]. |
rate | float | Non | La vitesse de la parole.Valeur par défaut : 1.0.Valeurs valides : [0.5, 2.0]. |
pitch | float | Non | Le ton.Valeur par défaut : 1.0.Valeurs valides : [0.5, 2.0]. |
bit_rate | int | Non | Le 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 : |
word_timestamp_enabled | bool | Non | Indique s'il faut activer les horodatages au niveau du mot.Valeur par défaut : false.Disponible uniquement en mode de sortie en flux. Voix compatibles : voix clonées de cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 et voix système marquées comme compatibles dans la liste des voix CosyVoice. Les voix clonées d'autres modèles ne prennent pas en charge cette fonction.Configurez word_timestamp_enabled via le dictionnaire parameters : |
seed | int | Non | Une 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_hints | list[str] | Non | 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 :
Valeurs valides
|
instruction | str | Non | Contrô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_tag | bool | Non | Indique 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. Seuls cosyvoice-v3-flash, cosyvoice-v3-plus et cosyvoice-v2 prennent en charge cette fonction. enable_aigc_tag, aigc_propagator et aigc_propagate_id via le dictionnaire parameters : |
aigc_propagator | str | Non | Dé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.Seuls cosyvoice-v3-flash, cosyvoice-v3-plus et cosyvoice-v2 prennent en charge cette fonction. parameters. Voir l'exemple de enable_aigc_tag. |
aigc_propagate_id | str | Non | Dé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.Seuls cosyvoice-v3-flash, cosyvoice-v3-plus et cosyvoice-v2 prennent en charge cette fonction. parameters. Voir l'exemple de enable_aigc_tag. |
hot_fix | dict | Non | Configure des corrections de prononciation et des remplacements de texte appliqués avant la synthèse. Cette fonction n'est pas compatible avec cosyvoice-v2.
|
enable_markdown_filter | bool | Non | Seules les voix clonées de cosyvoice-v3-flash prennent en charge cette fonction.
enable_markdown_filter via le dictionnaire parameters : |
Référence de l’API
stream() - streaming
Signature de la méthode :
| Paramètre | Type | Requis | Description |
|---|---|---|---|
text | str | Oui | Le texte complet à synthétiser. Longueur maximale: 20 000 caractères. |
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 :
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 :
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.
Métriques et réponses de la session (attributs de session)
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ésheader/payload). Le request_id de la requête la plus récente peut être obtenu depuis leheaderdesession.last_response, utile pour le dépannage et la corrélation de logs.
audio_chunks() - itérer les données audio
Signature de la méthode :
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 :
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 :
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 commefirst_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 :
| Champ | Type | Description |
|---|---|---|
type | str | Type 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_text | str | Le texte original de la phrase en cours. Renvoyé dans les événements sentence-begin et sentence-end. |
sentence | dict | Informations 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é). |
Qwen-Audio-TTS
Référence commune
- stream() - streaming
- send_text() - saisie en flux (méthode de session)
- stop() - terminer la saisie en flux (méthode de session)
- Métriques et réponses de la session (attributs de session)
- audio_chunks() - itérer les données audio
- events() - itérer les événements du serveur
- Gestion des erreurs
- Cycle de vie de la session
- Champ output dans les messages de events()
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
synthesize() - sans streaming
Signature de la méthode :| Paramètre | Type | Requis | Description |
|---|---|---|---|
text | str | Oui | Le texte complet à synthétiser. Longueur maximale: 20 000 caractères. |
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.
cancel() - annuler la synthèse en flux (méthode de session)
Signature de la méthode :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.
CosyVoice
Référence commune
- stream() - streaming
- send_text() - saisie en flux (méthode de session)
- stop() - terminer la saisie en flux (méthode de session)
- Métriques et réponses de la session (attributs de session)
- audio_chunks() - itérer les données audio
- events() - itérer les événements du serveur
- Gestion des erreurs
- Cycle de vie de la session
- Champ output dans les messages de events()
Ressource principale (client.audio.tts)
Chemin de la ressource : client.audio.tts
Description : 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
synthesize() - sans streaming
Signature de la méthode :| Paramètre | Type | Requis | Description |
|---|---|---|---|
text | str | Oui | Le texte complet à synthétiser. Longueur maximale: 20 000 caractères. |
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. synthesize et stream créent une nouvelle session à chaque appel ; il n'est pas nécessaire de réutiliser les instances.
cancel() - annuler la synthèse en flux (méthode de session)
Signature de la méthode :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.