Skip to main content

Referência do SDK Python de clonagem de voz do Qwen-Audio e CosyVoice

Clone e gerencie vozes do Qwen-Audio e CosyVoice com o SDK Python do DashScope.

Endpoint do service

O endpoint do SDK é determinado pelos parâmetros workspace e region do construtor do Client (correspondentes aos endpoints abaixo, que incluem o WorkspaceId). Para mudar para outra região, altere os parâmetros do construtor do Client para os valores da região desejada.
  • As API keys variam por região. Use a API key da região de destino.
  • A configuração de região é definida no nível do Client e afeta todas as chamadas de API do SDK DashScope feitas por esse Client.
  • Singapore
  • China (Beijing)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Substitua {WorkspaceId} pelo seu workspace ID real.
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

Recurso principal (client.audio.voices)

Finalidade: Gerencia o ciclo de vida das vozes clonadas Qwen-Audio-TTS, Qwen-Audio-Realtime e CosyVoice (criar, consultar, atualizar e excluir).

Construção do Client (autenticação e região)

import os
import dashscope

client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

create() — Crie uma voz

Assinatura do 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âmetroTipoObrigatórioDescrição
target_modelstrSimModelo de destino que usa a voz. Deve corresponder ao modelo usado nas solicitações posteriores com essa voz; caso contrário, as solicitações falham.
prefixstrSimPrefixo 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}.
urlstrSimÁudio de referência para clonagem de voz. Aceita uma URL acessível publicamente ou um Data URI codificado em Base64, como data:audio/wav;base64,....
language_hintsList[str]NãoAjuda 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 e deve conter exatamente um elemento.
Aplica-se 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.
  • 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: 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_lengthfloatNãoDuraçã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.
Aplica-se 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_preprocessboolNãoDefine 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.
Aplica-se 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_normalizationboolNãoDefine se o volume do áudio de amostra usado na clonagem de voz deve ser normalizado. Passe este parâmetro no dicionário extra_input. 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: Um objeto Voice, cujo campo voice_id é o ID da voz e cujo campo request_id é o ID da solicitação.

list() — Listar vozes

Assinatura do método:
def list(self, *, prefix: str = None, page_index: int = 0, page_size: int = 10, ...) -> VoiceList
Parâmetros:
ParâmetroTipoObrigatórioDescrição
prefixstrNãoFiltra pelo prefixo do nome da voz.
page_indexintNãoÍndice da página. Padrão: 0.
page_sizeintNãoNúmero de entradas por página. Padrão: 10.
Valor de retorno: Um objeto VoiceList, cujo campo voices é a lista de vozes e cujo campo request_id é o ID da solicitação. Cada item da lista é um dicionário. Use voice.get("target_model") para obter o ID do modelo de destino.

get() — Consultar detalhes da voz

Assinatura do método:
def get(self, voice_id: str, ...) -> Voice
Parâmetros:
ParâmetroTipoObrigatórioDescrição
voice_idstrSimID da voz a consultar.
Valor de retorno: Um objeto Voice com os detalhes da voz. Use voice.target_model para obter o ID do modelo de destino.

update() — Atualize uma voz

Assinatura do método:
def update(self, voice_id: str, *, url: str, ...) -> JobStatus
Parâmetros:
ParâmetroTipoObrigatórioDescrição
voice_idstrSimID da voz a atualizar.
urlstrSimNovo áudio de referência. Aceita uma URL acessível publicamente ou um Data URI codificado em Base64, como data:audio/wav;base64,....

delete() — Exclua uma voz

Assinatura do método:
def delete(self, voice_id: str, ...) -> JobStatus
Parâmetros:
ParâmetroTipoObrigatórioDescrição
voice_idstrSimID da voz a excluir.

Exemplos de código

Crie uma voz

import os
import dashscope

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do 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 chamadas frequentes. Cada chamada cria uma nova voz; ao atingir o limite de cota, não é possível criar mais vozes.
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"ID da solicitação: {voice.request_id}")
print(f"ID da voz: {voice.voice_id}")
Para um arquivo WAV local, substitua a atribuição de url acima pelo código a seguir antes de chamar client.audio.voices.create(). Para atualizar uma voz, passe também o Data URI pelo parâmetro url de client.audio.voices.update(). Substitua sample.wav pelo caminho do seu arquivo de áudio local.
import base64
from pathlib import Path

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

Listar vozes

import os
import dashscope

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Filtre por prefixo, ou defina como None para listar todas
voices = client.audio.voices.list(prefix='myvoice', page_index=0, page_size=10)

print(f"ID da solicitação: {voices.request_id}")
print(f"Vozes encontradas: {voices.voices}")
for voice in voices.voices:
    print(f"Modelo de destino: {voice.get('target_model')}")

Consultar uma voz específica

import os
import dashscope

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do 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"ID da solicitação: {voice_details.request_id}")
print(f"Detalhes da voz: {voice_details}")
print(f"Modelo de destino: {voice_details.target_model}")

Atualize uma voz

import os
import dashscope

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do 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"Atualização enviada. ID da solicitação: {result.request_id}")

Exclua uma voz

import os
import dashscope

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do 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"Exclusão enviada. ID da solicitação: {result.request_id}")