Referencia del SDK de Python para clonación de voz de Qwen-Audio y CosyVoice

Endpoint de servicio

El endpoint del SDK está determinado por los parámetros workspace y region del constructor del Client (correspondientes a los endpoints siguientes, que incluyen el WorkspaceId). Para cambiar a una región diferente, modifique los parámetros del constructor del Client por los valores de esa región.

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 a nivel de Client y afecta a todas las llamadas de API del SDK de DashScope realizadas a través de ese Client.

Singapore
China (Beijing)

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Alibaba 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

Recurso principal (`client.audio.voices`)

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

Construcción del Client (autenticación y región)

import os
import dashscope

client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # La siguiente configuración corresponde a la región de Singapur. Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

create() — Crear una voz

Firma del método:

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

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. Se 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. Se 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. Se 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 en el diccionario `extra_input`. 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: Un objeto Voice, cuyo voice_id es el ID de la voz y cuyo request_id es el ID de la solicitud.

list() — Listar voces

Firma del método:

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

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: Un objeto VoiceList, cuyo voices es la lista de voces y cuyo request_id es el ID de la solicitud.

get() — Consultar detalles de la voz

Firma del método:

def get(self, voice_id: str, ...) -> Voice

Parámetros:

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

Valor de retorno: Un objeto Voice con los detalles de la voz.

update() — Actualizar una voz

Firma del método:

def update(self, voice_id: str, *, url: str, ...) -> JobStatus

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() — Eliminar una voz

Firma del método:

def delete(self, voice_id: str, ...) -> JobStatus

Parámetros:

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

Ejemplos de código

Crear una voz

import os
import dashscope

# La siguiente configuración corresponde a la región de Singapur. Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su 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'

# Evite llamadas frecuentes. Cada llamada crea una nueva voz; una vez alcanzado el límite de cuota, no se pueden crear más.
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}")

Para un archivo WAV local, sustituya la asignación de url anterior por el siguiente código antes de llamar a client.audio.voices.create(). Para actualizar una voz, pase también el Data URI mediante el parámetro url de client.audio.voices.update(). 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 os
import dashscope

# La siguiente configuración corresponde a la región de Singapur. Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Filtra por prefijo, o establezca None para listar todo
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}")

Consultar una voz específica

import os
import dashscope

# La siguiente configuración corresponde a la región de Singapur. Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su 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}")

Actualizar una voz

import os
import dashscope

# La siguiente configuración corresponde a la región de Singapur. Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su 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}")

Eliminar una voz

import os
import dashscope

# La siguiente configuración corresponde a la región de Singapur. Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su 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}")

​Endpoint de servicio

​Recurso principal (client.audio.voices)

​Construcción del Client (autenticación y región)

​create() — Crear una voz

​list() — Listar voces

​get() — Consultar detalles de la voz

​update() — Actualizar una voz

​delete() — Eliminar una voz

​Ejemplos de código

​Crear una voz

​Listar voces

​Consultar una voz específica

​Actualizar una voz

​Eliminar una voz

Endpoint de servicio

Recurso principal (`client.audio.voices`)

Construcción del Client (autenticación y región)

create() — Crear una voz

list() — Listar voces

get() — Consultar detalles de la voz

update() — Actualizar una voz

delete() — Eliminar una voz

Ejemplos de código

Crear una voz

Listar voces

Consultar una voz específica

Actualizar una voz

Eliminar una voz