Skip to main content

Référence du SDK Python de clonage de voix pour Qwen-Audio et CosyVoice

Clonez et gérez les voix Qwen-Audio et CosyVoice avec le SDK Python de DashScope.

Endpoint du service

L'endpoint du SDK est déterminé par les paramètres workspace et region du constructeur du Client (correspondant aux adresses ci-dessous, qui incluent le WorkspaceId). Pour changer de région, modifiez les paramètres du constructeur du Client avec les valeurs de la région cible.
  • Les clés API varient selon la région. Utilisez la clé API de la région cible.
  • La configuration de région s'effectue au niveau du Client et affecte tous les appels d'API du SDK DashScope effectués via ce Client.
  • Singapore
  • China (Beijing)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Remplacez {WorkspaceId} par votre 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 de meilleures performances et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • Chine (Pékin) : de dashscope.aliyuncs.com vers {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapour : de dashscope-intl.aliyuncs.com vers {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Ressource principale (client.audio.voices)

Objectif : Gère le cycle de vie des voix clonées Qwen-Audio-TTS, Qwen-Audio-Realtime et CosyVoice (création, consultation, mise à jour et suppression).

Construction du Client (authentification et région)

import os
import dashscope

client = dashscope.Client(
    # 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"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Voici la configuration de la région de Chine (Pékin). Remplacez "{WorkspaceId}" par l'ID de votre workspace. La configuration varie selon la région.
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

create() — Créer une voix

Signature de la méthode :
def create(self, *, target_model: str, prefix: str, url: str,
           language_hints: List[str] = None,
           max_prompt_audio_length: float = None,
           extra_input: Dict = None,
           parameters: Dict = None, ...) -> Voice
Paramètres :
ParamètreTypeObligatoireDescription
target_modelstrOuiModèle cible qui utilise la voix. Il doit correspondre au modèle utilisé dans les requêtes ultérieures avec cette voix, sinon les requêtes échouent.
prefixstrOuiPréfixe du nom de la voix. Seuls les caractères alphanumériques sont autorisés, avec une longueur maximale de 10 caractères. Le nom de voix résultant suit ce format : {target_model}-{prefix}-{unique_id}.
urlstrOuiAudio de référence pour le clonage vocal. Accepte une URL accessible publiquement ou un Data URI encodé en Base64, par exemple data:audio/wav;base64,....
language_hintsList[str]NonAide le modèle à identifier la langue de l'échantillon audio afin d'extraire les caractéristiques vocales plus précisément et d'améliorer la qualité du clonage. Si la langue spécifiée ne correspond pas à la langue réelle de l'audio (par exemple, définir en alors que l'audio est en chinois), le système ignore cette valeur et détecte automatiquement la langue.Ce paramètre est un tableau qui doit contenir exactement un élément.
S’applique à qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus, cosyvoice-v3-flash.
  • qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash :
    • 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
    • it : Italien
    • es : Espagnol
    • ms : Malais
    • fil : Filipino
    • ar : Arabe
  • cosyvoice-v3-plus :
    • zh : Chinois
    • en : Anglais
    • fr : Français
    • de : Allemand
    • ja : Japonais
    • ko : Coréen
    • ru : Russe
  • cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash :
    • 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
Valeur par défaut : ["zh"].
max_prompt_audio_lengthfloatNonDurée maximale (en secondes) de l'audio de référence après prétraitement. Valeurs valides : [3,0, 30,0].Valeur par défaut : 10,0.
S’applique à qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
enable_preprocessboolNonIndique s'il faut activer le prétraitement audio (réduction du bruit, amélioration audio et normalisation du volume). Activez cette option pour les enregistrements comportant du bruit de fond. Désactivez-la pour les enregistrements réalisés dans des environnements calmes afin de préserver les caractéristiques vocales d'origine.Valeur par défaut : false.
S’applique à qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
enable_volume_normalizationboolNonDétermine si le volume de l'échantillon audio utilisé pour le clonage vocal doit être normalisé. Transmettez ce paramètre dans le dictionnaire extra_input. Valeur par défaut : False. Si vous définissez ce paramètre sur True, le volume de l'audio synthétisé avec la voix créée peut différer de celui d'un audio synthétisé avec une voix créée sans cette option.
Valeur de retour : un objet Voice, dont voice_id est l'identifiant de la voix et request_id l'identifiant de la requête.

list() — Lister les voix

Signature de la méthode :
def list(self, *, prefix: str = None, page_index: int = 0, page_size: int = 10, ...) -> VoiceList
Paramètres :
ParamètreTypeObligatoireDescription
prefixstrNonFiltrer par préfixe de nom de voix.
page_indexintNonIndex de la page. Valeur par défaut : 0.
page_sizeintNonNombre d'entrées par page. Valeur par défaut : 10.
Valeur de retour : un objet VoiceList, dont voices est la liste des voix et request_id l'identifiant de la requête. Chaque élément de la liste est un dictionnaire. Utilisez voice.get("target_model") pour obtenir l’identifiant du modèle cible.

get() — Consulter les détails d'une voix

Signature de la méthode :
def get(self, voice_id: str, ...) -> Voice
Paramètres :
ParamètreTypeObligatoireDescription
voice_idstrOuiL'identifiant de la voix à consulter.
Valeur de retour : un objet Voice contenant les détails de la voix. Utilisez voice.target_model pour obtenir l’identifiant du modèle cible.

update() — Mettre à jour une voix

Signature de la méthode :
def update(self, voice_id: str, *, url: str, ...) -> JobStatus
Paramètres :
ParamètreTypeObligatoireDescription
voice_idstrOuiL'identifiant de la voix à mettre à jour.
urlstrOuiNouvel audio de référence. Accepte une URL accessible publiquement ou un Data URI encodé en Base64, par exemple data:audio/wav;base64,....

delete() — Supprimer une voix

Signature de la méthode :
def delete(self, voice_id: str, ...) -> JobStatus
Paramètres :
ParamètreTypeObligatoireDescription
voice_idstrOuiL'identifiant de la voix à supprimer.

Exemples de code

Créer une voix

import os
import dashscope

# 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(
    # 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"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

TARGET_MODEL = 'qwen-audio-3.1-tts-plus'
voice_prefix = 'myvoice'
url = 'https://your-audio-file-url'

# Évitez les appels fréquents. Chaque appel crée une nouvelle voix ; une fois le quota
# atteint, impossible d'en créer davantage.
voice = client.audio.voices.create(
    target_model=TARGET_MODEL,
    prefix=voice_prefix,
    url=url,
    max_prompt_audio_length=10,
    # extra_input={'enable_preprocess': False, 'enable_volume_normalization': True}
)

print(f"Request ID: {voice.request_id}")
print(f"Voice ID: {voice.voice_id}")
Pour un fichier WAV local, remplacez l'affectation de url ci-dessus par le code suivant avant d'appeler create. Pour mettre à jour une voix, transmettez également le Data URI dans le paramètre url de update. Remplacez sample.wav par le chemin de votre fichier audio local.
import base64
from pathlib import Path

url = "data:audio/wav;base64," + base64.b64encode(
    Path("sample.wav").read_bytes()
).decode("ascii")

Lister les voix

import os
import dashscope

# 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(
    # 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"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Filtre par préfixe, ou définir None pour lister toutes les voix
voices = client.audio.voices.list(prefix='myvoice', page_index=0, page_size=10)

print(f"Request ID: {voices.request_id}")
print(f"Found voices: {voices.voices}")
for voice in voices.voices:
    print(f"Modèle cible: {voice.get('target_model')}")

Consulter une voix spécifique

import os
import dashscope

# 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(
    # 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"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

voice_id = 'qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx'

voice_details = client.audio.voices.get(voice_id=voice_id)

print(f"Request ID: {voice_details.request_id}")
print(f"Voice Details: {voice_details}")
print(f"Modèle cible: {voice_details.target_model}")

Mettre à jour une voix

import os
import dashscope

# 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(
    # 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"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

result = client.audio.voices.update(
    voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx',
    url='https://your-new-audio-file-url'
)
print(f"Update submitted. Request ID: {result.request_id}")

Supprimer une voix

import os
import dashscope

# 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(
    # 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"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

result = client.audio.voices.delete(voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx')
print(f"Deletion submitted. Request ID: {result.request_id}")