SDK de Python para clonación de voz de Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice - Alibaba Cloud Model Studio

La clonación de voz de Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice está disponible a través del SDK de Python de DashScope.

Endpoint de servicio

El SDK utiliza el endpoint de la región de China (Beijing) de forma predeterminada. Para cambiar a una región diferente, configure dashscope.base_http_api_url antes de inicializar el cliente.

Nota

Las API keys varían por región. Use la API key de la región de destino.
La configuración de región es global y afecta a todas las llamadas de API del SDK de DashScope.

Singapore

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

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

China (Beijing)

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

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

ImportanteAlibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Beijing) y Singapur. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:

China (Pekín): de dashscope.aliyuncs.com a {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapur: de dashscope-intl.aliyuncs.com a {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Clase VoiceEnrollmentService

Ruta del paquete: dashscope.audio.tts_v2.VoiceEnrollmentService

Propósito: Administra el ciclo de vida de las voces clonadas de Qwen-Audio-TTS, Qwen-Audio-Realtime y CosyVoice (crear, consultar, actualizar y eliminar).

Constructor

VoiceEnrollmentService()

create_voice() — Crear una voz

Firma del método:

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

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
target_model	str	Sí	Modelo de destino que usa la voz. Debe coincidir con el modelo usado en las solicitudes posteriores con esta voz; de lo contrario, las solicitudes fallan.
prefix	str	Sí	Un prefijo para el nombre de la voz. Solo se permiten caracteres alfanuméricos, con una longitud máxima de 10 caracteres. El nombre de voz resultante sigue este formato: `{target_model}-{prefix}-{unique_id}`.
url	str	Sí	Audio de referencia para la clonación de voz. Acepta una URL de acceso público o un Data URI codificado en Base64, por ejemplo, `data:audio/wav;base64,...`.
language_hints	List[str]	No	Ayuda al modelo a identificar el idioma del audio de muestra para extraer características de voz con mayor precisión y mejorar la calidad de la clonación. Si el idioma especificado no coincide con el idioma real del audio (por ejemplo, establecer `en` cuando el audio está en chino), el sistema ignora este valor y detecta el idioma automáticamente. Este parámetro es una matriz y debe contener exactamente un elemento. NotaSe aplica a 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. Haga clic para ver los idiomas compatibles por modelo 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: Chino en: Inglés fr: Francés de: Alemán ja: Japonés ko: Coreano ru: Ruso pt: Portugués th: Tailandés id: Indonesio vi: Vietnamita it: Italiano es: Español ms: Malayo fil: Filipino ar: Árabe cosyvoice-v3-plus: zh: Chino en: Inglés fr: Francés de: Alemán ja: Japonés ko: Coreano ru: Ruso cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: zh: Chino en: Inglés fr: Francés de: Alemán ja: Japonés ko: Coreano ru: Ruso pt: Portugués th: Tailandés id: Indonesio vi: Vietnamita Valor predeterminado: ["zh"].
max_prompt_audio_length	float	No	La duración máxima (en segundos) del audio de referencia después del preprocesamiento. Valores válidos: [3.0, 30.0]. Predeterminado: 10.0. NotaSe aplica a 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	No	Indica si se debe habilitar el preprocesamiento de audio (reducción de ruido, mejora de audio y normalización de volumen). Habilite esta opción para grabaciones con ruido de fondo. Desactívela para grabaciones en entornos silenciosos para preservar las características originales de la voz. Predeterminado: false. NotaSe aplica a 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	No	Especifica si se debe normalizar el volumen del audio de muestra utilizado para la clonación de voz. Pase este parámetro directamente como un argumento de palabra clave. Valor predeterminado: `False`. Si configura este parámetro en `True`, el volumen del audio sintetizado con la voz creada puede diferir del audio sintetizado con una voz creada con este parámetro deshabilitado.

Valor de retorno: str — El ID de la voz (voice_id).

list_voices() — Listar voces

Firma del método:

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

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
prefix	str	No	Filtrar por prefijo de nombre de voz.
page_index	int	No	Índice de página. Valor predeterminado: 0.
page_size	int	No	Número de entradas por página. Valor predeterminado: 10.

Valor de retorno: list — Una lista de voces.

query_voice() — Consultar detalles de la voz

Firma del método:

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

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
voice_id	str	Sí	El ID de voz a consultar.

Valor de retorno: dict — Detalles de la voz.

update_voice() — Actualizar una voz

Firma del método:

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

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
voice_id	str	Sí	El ID de voz a actualizar.
url	str	Sí	Nuevo audio de referencia. Acepta una URL de acceso público o un Data URI codificado en Base64, por ejemplo, `data:audio/wav;base64,...`.

delete_voice() — Eliminar una voz

Firma del método:

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

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
voice_id	str	Sí	El ID de voz a eliminar.

Ejemplos de código

Los siguientes ejemplos muestran cómo utilizar la clase VoiceEnrollmentService para operaciones comunes de clonación de voz.

Crear una voz

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}")

Para un archivo WAV local, sustituya la asignación de url anterior por el siguiente código antes de llamar a create_voice. Para actualizar una voz, pase también el Data URI mediante el parámetro url de update_voice. Sustituya sample.wav por la ruta de su archivo de audio local.

import base64
from pathlib import Path

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

Listar voces

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}")

Consultar una voz específica

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}")

Actualizar una voz

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()}")

Eliminar una voz

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()}")