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.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)
create() — Crie uma voz
Assinatura do método:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| target_model | str | Sim | Modelo 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. |
| 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 | Á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_hints | List[str] | Não | 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 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.
Clique para ver os idiomas compatíveis por modelo
|
| max_prompt_audio_length | float | Não | 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. 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_preprocess | bool | Não | 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. 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_normalization | bool | Não | Define 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. |
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:
| 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. |
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:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| voice_id | str | Sim | ID da voz a consultar. |
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:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| voice_id | str | Sim | ID da voz a atualizar. |
| url | str | Sim | Novo á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:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| voice_id | str | Sim | ID da voz a excluir. |
Exemplos de código
Crie uma voz
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.