Skip to main content

API HTTP de clonagem de voz: Qwen-Audio e CosyVoice

Parâmetros HTTP, respostas e exemplos de clonagem de voz para Qwen-Audio e CosyVoice.

Esta referência abrange Qwen-Audio-TTS, Qwen-Audio-Realtime e CosyVoice. Primeiro, obtenha uma chave de API e configure as variáveis de ambiente. Os exemplos de solicitação leem DASHSCOPE_API_KEY. Ao gerenciar a mesma voz em diferentes APIs, use a mesma conta. Para as definições dos SDKs, consulte Java SDK e Python SDK.

Endpoint do serviço

  • China (Pequim)
  • Singapura
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization
Substitua {WorkspaceId} pelo ID do workspace real, disponível na página Workspace Details do console do Alibaba Cloud Model Studio. As chaves de API de Pequim e Singapura são diferentes.
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 desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos migrar para os novos domínios:
  • Região China (Pequim): migre de dashscope.aliyuncs.com para {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
  • Região Singapura: migre de dashscope-intl.aliyuncs.com para {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com.
Os domínios existentes continuam funcionando normalmente.

Cabeçalhos da solicitação

ParâmetroTipoObrigatórioDescrição
AuthorizationstringSimToken de autenticação no formato Bearer <your_api_key>. Substitua <your_api_key> pela sua chave de API real.
Content-TypestringSimDefina como application/json.

Requisitos de áudio e custos

Consulte os requisitos de áudio no Guia de clonagem de voz. O processo de clonagem do Qwen-Audio-Realtime está em Clonagem de voz para conversas em tempo real. A criação de uma voz com o Qwen-Audio-Realtime é gratuita; as chamadas ao modelo são cobradas conforme o modelo de destino. Consulte Informações de cobrança e os limites em Informações de cota.

Corpo da solicitação

model string — ObrigatórioDefina como voice-enrollment.input object — Obrigatório

Propriedades

action string — ObrigatórioOperação:
  • create_voice: Criar uma voz.
  • list_voice: Listar vozes.
  • query_voice: Consultar detalhes de uma voz.
  • update_voice: Atualizar uma voz.
  • delete_voice: Excluir uma voz.
target_model string — Obrigatório na criaçãoModelo que usará a voz. Ele deve corresponder ao modelo das chamadas posteriores de síntese ou conversa; caso contrário, a chamada falha.Escolha um modelo Qwen-Audio-TTS, Qwen-Audio-Realtime ou CosyVoice que ofereça clonagem de voz. Consulte os IDs e as regiões em Modelos compatíveis.audio string — Obrigatório na criação ou atualização se url não for fornecidoÁudio de referência para criação ou novo áudio de referência para atualização. Aceita uma URL acessível publicamente ou um Data URI Base64, como data:audio/wav;base64,....
Compatível com o parâmetro legado url. Quando url for usado, audio pode ser omitido. url será descontinuado; recomenda-se migrar para audio.
prefix string — Obrigatório na criação; opcional na listagemNa criação: prefixo do nome da voz. Permite apenas dígitos e letras inglesas, com no máximo 10 caracteres. O nome gerado tem o formato {target_model}-{prefix}-{unique_id}.Na listagem: filtra as vozes pelo prefixo do nome.language_hints array[string] — Opcional na criaçãoAuxilia 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 1 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.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus e 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.1-realtime-flash, qwen-audio-3.0-realtime-plus e 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 e 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
Valor padrão: ["zh"].max_prompt_audio_length float — Opcional na criaçãoDuração máxima, em segundos, do áudio de referência usado na clonagem após o pré-processamento. Intervalo de valores: [3.0, 30.0].Valor 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.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash e cosyvoice-v3-flash.
enable_preprocess boolean — Opcional na criaçãoDefine se o pré-processamento de áudio será ativado, incluindo redução de ruído, realce de áudio e normalização de volume. Ative-o para gravações com ruído de fundo. Desative-o em gravações feitas em ambientes silenciosos para preservar 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.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash e cosyvoice-v3-flash.
enable_volume_normalization string — Opcional na criaçãoDefine se o volume do áudio de exemplo usado na clonagem de voz será normalizado. Valores:
  • "true": Ativa a normalização de volume.
  • "false": desativa a normalização de volume.
Quando ativado, o áudio sintetizado com a voz criada pode ter um volume diferente daquele obtido com este parâmetro desativado.Valor padrão: "false".page_index integer — Opcional na listagemÍndice da página.page_size integer — Opcional na listagemNúmero de entradas por página.voice_id string — Obrigatório para consultar, atualizar ou excluirID da voz a consultar, atualizar ou excluir.

Exemplos de solicitação

  • Criar
  • Listar
  • Consultar detalhes
  • Atualizar
  • Excluir
O exemplo usa qwen-audio-3.1-tts-plus. Substitua target_model em input pelo ID real do modelo de destino.A configuração a seguir se aplica à região Singapura. Substitua "{WorkspaceId}" pelo ID real do workspace. A configuração varia conforme a região.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "qwen-audio-3.1-tts-plus",
        "prefix": "myvoice",
        "audio": "https://your-audio-url.wav",
        "language_hints": ["en"],
        "enable_volume_normalization": "false"
    }
}'
Ao usar um arquivo de áudio WAV local, gere uma URI de dados Base64 com o código a seguir e defina o valor de audio no campo audio do objeto input da solicitação de criação ou atualização. Substitua sample.wav pelo caminho do arquivo de áudio local.
import base64
from pathlib import Path

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

Corpo da resposta

request_id stringIdentificador exclusivo desta solicitação.output objectContém os campos de criação, listagem ou consulta de detalhes. A atualização não retorna dados de negócio. A resposta pode incluir preview_audio, um objeto vazio que pode ser ignorado. A exclusão retorna um objeto vazio.
voice_id string — Retornado na criaçãoID da voz.voice_list array[object] — Retornado na listagemLista de vozes encontradas.
voice_id stringID da voz.target_model stringModelo de destino que usa a voz, para síntese de fala ou conversa por voz em tempo real.gmt_create stringData e hora de criação da voz.gmt_modified stringHora da última modificação.status stringEstado da voz; consulte os valores válidos em "Descrição dos estados da voz".
resource_link string — Retornado na consulta de detalhesURL do arquivo de áudio.gmt_create string — Retornado na consulta de detalhesData e hora de criação da voz.gmt_modified string — Retornado na consulta de detalhesHora da última modificação.status string — Retornado na consulta de detalhesEstado da voz; consulte os valores válidos em "Descrição dos estados da voz".target_model string — Retornado na consulta de detalhesModelo de destino que usa a voz, para síntese de fala ou conversa por voz em tempo real.
usage objectInformações de uso desta solicitação.
count integerSempre 1. Na criação, indica o número de vozes criadas.

Exemplos de resposta

  • Criar
  • Listar
  • Consultar detalhes
  • Atualizar
  • Excluir
{
    "output": {
        "voice_id": "qwen-audio-3.1-tts-plus-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Descrições de status de voz

As vozes criadas passam por um processo de revisão.
StatusDescrição
DEPLOYINGEm revisão ou processamento.
OKRevisão aprovada. A voz está pronta para uso.
UNDEPLOYEDAnálise rejeitada. A voz não pode ser usada.

Mensagens de erro

Se encontrar erros, consulte Error codes para solução de problemas.