Referência do SDK Python para clonagem de voz

Guia do usuário: Voice cloning.

Endpoint do service

O sdk usa o endpoint da região China (Beijing) por padrão. Para mudar para outra região, defina dashscope.base_http_api_url antes de inicializar o cliente.

Singapore
China (Beijing)

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Substitua {WorkspaceId} pelo seu workspace ID real.

Mudar para a região Singapore:

import dashscope

# Set at the beginning of your code
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

Note :

As chaves de API variam conforme a região. Use a chave correspondente à região de destino.

A configuração de região é global e afeta todas as chamadas de API do DashScope sdk.

O Alibaba Cloud Model Studio lançou domínios específicos por workspace para as regiões China (Beijing) e Singapore. Os novos domínios dedicados oferecem melhor desempenho e maior estabilidade nas solicitações de inferência. Recomendamos migrar para os novos domínios:

China (Beijing): de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: de dashscope-intl.aliyuncs.com para {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Substitua {WorkspaceId} pelo seu Workspace ID real. Os domínios existentes permanecem totalmente funcionais.

Classe VoiceEnrollmentService

Caminho do pacote: dashscope.audio.tts_v2.VoiceEnrollmentService Finalidade: Gerencia o ciclo de vida das vozes clonadas do Qwen-Audio-TTS/CosyVoice, incluindo criação, consulta, atualização e exclusão.

Construtor

VoiceEnrollmentService()

create_voice() — Crie uma voz

Assinatura do 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	Obrigatório	Descrição
target_model	str	Sim	Modelo de texto para fala (TTS) que gera a voz clonada. Deve corresponder ao modelo especificado na chamada da API TTS; caso contrário, a síntese falhará.
prefix	str	Sim	Prefixo do nome da voz. Permite apenas caracteres alfanuméricos, com comprimento máximo de 10 caracteres. O nome final da voz segue este formato: `{target_model}-{prefix}-{unique_id}`.
url	str	Sim	URL do arquivo de áudio para clonagem de voz. A URL deve ter acesso público.
language_hints	List[str]	Não	Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando o modelo é `voice-enrollment`). Compatível somente com qwen-audio-3,0-tts-plus,qwen-audio-3,0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, v3-plus e v3-flash. Ajuda o modelo a identificar o idioma do áudio de amostra para extrair características vocais com mais precisão e melhorar a qualidade da clonagem. Se o idioma especificado não corresponder ao idioma real do áudio (por exemplo, definir `en` quando o áudio está em chinês), o sistema ignora esse valor e detecta o idioma automaticamente. Este parâmetro é um array, mas a versão atual processa apenas o primeiro elemento. Os valores válidos variam conforme o modelo: qwen-audio-3,0-tts-plus,qwen-audio-3,0-tts-flash: zh: Chinês en: Inglês fr: Francês de: Alemão ja: Japonês ko: Coreano ru: Russo pt: Português th: Tailandês id: Indonésio vi: Vietnamita it: Italiano es: Espanhol ms: Malaio fil: Filipino ar: Árabe cosyvoice-v3-plus: zh: Chinês en: Inglês fr: Francês de: Alemão ja: Japonês ko: Coreano ru: Russo cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: zh: Chinês en: Inglês fr: Francês de: Alemão ja: Japonês ko: Coreano ru: Russo pt: Português th: Tailandês id: Indonésio vi: Vietnamita Padrão: ["zh"].
max_prompt_audio_length	float	Não	Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando o modelo é `voice-enrollment`). Compatível somente com qwen-audio-3,0-tts-plus,qwen-audio-3,0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash e v3-flash. Duração máxima (em segundos) do áudio de referência após o pré-processamento. Valores válidos: [3,0, 30,0]. Padrão: 10,0.
enable_preprocess	bool	Não	Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando o modelo é `voice-enrollment`). Compatível somente com qwen-audio-3,0-tts-plus,qwen-audio-3,0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash e v3-flash. Define se o pré-processamento de áudio deve ser ativado (redução de ruído, aprimoramento de áudio e normalização de volume). Ative esta opção para gravações com ruído de fundo. Desative-a para gravações em ambientes silenciosos e preserve as características originais da voz. Padrão: false.
enable_volume_normalization	bool	Não	Define se o volume do áudio de amostra usado na clonagem de voz deve ser normalizado. Passe este parâmetro diretamente como argumento nomeado. Valor padrão: `False`. Se você definir este parâmetro como `True`, o volume do áudio sintetizado com a voz criada poderá diferir daquele sintetizado com uma voz criada com este parâmetro desativado.

Valor de retorno: str — O ID da voz (voice_id).

list_voices() — Listar vozes

Assinatura do método:

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

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
prefix	str	Não	Filtra pelo prefixo do nome da voz.
page_index	int	Não	Índice da página. Padrão: 0.
page_size	int	Não	Número de entradas por página. Padrão: 10.

Valor de retorno: list — Uma lista de vozes.

query_voice() — Consultar detalhes da voz

Assinatura do método:

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

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
voice_id	str	Sim	ID da voz a consultar.

Valor de retorno: dict — Detalhes da voz.

update_voice() — Atualize uma voz

Assinatura do método:

def update_voice(self, voice_id: str, url: str, language_hints: List[str] = None,
                 max_prompt_audio_length: float = None, enable_preprocess: bool = None) -> None

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
voice_id	str	Sim	ID da voz a atualizar.
url	str	Sim	Nova URL do arquivo de áudio.
language_hints	List[str]	Não	Dicas de idioma para o áudio de amostra.
max_prompt_audio_length	float	Não	Duração máxima do áudio de referência.
enable_preprocess	bool	Não	Define se o pré-processamento de áudio deve ser ativado.

delete_voice() — Exclua uma voz

Assinatura do método:

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

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
voice_id	str	Sim	ID da voz a excluir.

Exemplos de código

Os exemplos a seguir mostram como usar a classe VoiceEnrollmentService para operações comuns de clonagem de voz.

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

Listar vozes

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

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

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

​Endpoint do service

​Classe VoiceEnrollmentService

​Construtor

​create_voice() — Crie uma voz

​list_voices() — Listar vozes

​query_voice() — Consultar detalhes da voz

​update_voice() — Atualize uma voz

​delete_voice() — Exclua uma voz

​Exemplos de código

​Crie uma voz

​Listar vozes

​Consultar uma voz específica

​Atualize uma voz

​Exclua uma voz

Endpoint do service

Classe VoiceEnrollmentService

Construtor

create_voice() — Crie uma voz

list_voices() — Listar vozes

query_voice() — Consultar detalhes da voz

update_voice() — Atualize uma voz

delete_voice() — Exclua uma voz

Exemplos de código

Crie uma voz

Listar vozes

Consultar uma voz específica

Atualize uma voz

Exclua uma voz