SDK Python de clonage vocal Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice - Alibaba Cloud Model Studio

Le clonage vocal Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice est disponible via le SDK Python DashScope.

Endpoint du service

Par défaut, le SDK utilise l'endpoint de la région Chine (Pékin). Pour changer de région, définissez dashscope.base_http_api_url avant d'initialiser le client.

Remarque

Les clés API varient selon la région. Utilisez la clé API de la région cible.
Le paramètre de région est global et affecte tous les appels d’API du SDK DashScope.

Singapore

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

Remplacez {WorkspaceId} par votre ID d'espace de travail.

China (Beijing)

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1

Remplacez {WorkspaceId} par votre ID d'espace de travail.

ImportantAlibaba 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

Classe VoiceEnrollmentService

Chemin du package : dashscope.audio.tts_v2.VoiceEnrollmentService

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

Constructeur

VoiceEnrollmentService()

create_voice() — Créer une voix

Signature de la méthode :

def create_voice(self, target_model: str, prefix: str, url: str,
                 language_hints: List[str] = None,
                 max_prompt_audio_length: float = None,
                 **kwargs) -> str

Paramètres :

Paramètre	Type	Obligatoire	Description
target_model	str	Oui	Modè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.
prefix	str	Oui	Pré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}`.
url	str	Oui	Audio 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_hints	List[str]	Non	Aide 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. RemarqueS’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. Cliquez pour voir les langues prises en charge par modèle 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_length	float	Non	Duré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. RemarqueS’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_preprocess	bool	Non	Indique 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. RemarqueS’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_normalization	bool	Non	Détermine si le volume de l'échantillon audio utilisé pour le clonage vocal doit être normalisé. Transmettez ce paramètre directement comme argument nommé. 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 : str — L'identifiant de la voix (voice_id).

list_voices() — Lister les voix

Signature de la méthode :

def list_voices(self, prefix: str = None, page_index: int = 0, page_size: int = 10) -> list

Paramètres :

Paramètre	Type	Obligatoire	Description
prefix	str	Non	Filtrer par préfixe de nom de voix.
page_index	int	Non	Index de la page. Valeur par défaut : 0.
page_size	int	Non	Nombre d'entrées par page. Valeur par défaut : 10.

Valeur de retour : list — Une liste de voix.

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

Signature de la méthode :

def query_voice(self, voice_id: str) -> dict

Paramètres :

Paramètre	Type	Obligatoire	Description
voice_id	str	Oui	L'identifiant de la voix à consulter.

Valeur de retour : dict — Détails de la voix.

update_voice() — Mettre à jour une voix

Signature de la méthode :

def update_voice(self, voice_id: str, url: str) -> None

Paramètres :

Paramètre	Type	Obligatoire	Description
voice_id	str	Oui	L'identifiant de la voix à mettre à jour.
url	str	Oui	Nouvel audio de référence. Accepte une URL accessible publiquement ou un Data URI encodé en Base64, par exemple `data:audio/wav;base64,...`.

delete_voice() — Supprimer une voix

Signature de la méthode :

def delete_voice(self, voice_id: str) -> None

Paramètres :

Paramètre	Type	Obligatoire	Description
voice_id	str	Oui	L'identifiant de la voix à supprimer.

Exemples de code

Les exemples suivants illustrent l'utilisation de la classe VoiceEnrollmentService pour les opérations courantes de clonage vocal.

Créer une voix

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# The following uses the Singapore region endpoint. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

TARGET_MODEL = 'qwen-audio-3.0-tts-flash'
voice_prefix = 'myvoice'
url = 'https://your-audio-file-url'
service = VoiceEnrollmentService()

# Avoid frequent calls. Each call creates a new voice, and you can't create
# more after reaching the quota limit.
voice_id = service.create_voice(
    target_model=TARGET_MODEL,
    prefix=voice_prefix,
    url=url,
    max_prompt_audio_length=10,
    # enable_preprocess=False,
    # enable_volume_normalization=True
)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Voice ID: {voice_id}")

Pour un fichier WAV local, remplacez l’affectation de url ci-dessus par le code suivant avant d’appeler create_voice. Pour mettre à jour une voix, transmettez également le Data URI dans le paramètre url de update_voice. 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 dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# The following uses the Singapore region endpoint. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()

# Filter by prefix, or set to None to list all voices
voices = service.list_voices(prefix='myvoice', page_index=0, page_size=10)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Found voices: {voices}")

Consulter une voix spécifique

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# The following uses the Singapore region endpoint. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
voice_id = 'qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx'

voice_details = service.query_voice(voice_id=voice_id)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Voice Details: {voice_details}")

Mettre à jour une voix

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# The following uses the Singapore region endpoint. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
service.update_voice(
    voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx',
    url='https://your-new-audio-file-url'
)
print(f"Update submitted. Request ID: {service.get_last_request_id()}")

Supprimer une voix

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# The following uses the Singapore region endpoint. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
service.delete_voice(voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx')
print(f"Deletion submitted. Request ID: {service.get_last_request_id()}")