Skip to main content
Referência da API de Clonagem de Voz

Voice cloning HTTP API reference

Utilize a API HTTP para criar, listar, consultar, atualizar e excluir vozes clonadas.

Guia do usuário: Voice cloning.

Endpoint do service

  • Singapore
  • China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customizationSubstitua {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 desempenho superior e maior estabilidade para solicitações de inferência. Recomendamos a migração 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.

Cabeçalhos da solicitação

Parâmetro

Tipo

Obrigatório

Descrição

Authorization

string

Sim

Token de autenticação no formato Bearer <your_api_key>. Substitua <your_api_key> pela sua chave de API real.

Content-Type

string

Sim

Tipo de mídia do corpo da solicitação. Defina como application/json para Qwen-Audio-TTS/CosyVoice/Qwen-TTS ou application/json; charset=utf-8 para MiniMax.

Crie uma voz

Corpo da solicitação

Este exemplo utiliza o endpoint da região de Singapore. Para a região de Beijing, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Substitua {WorkspaceId} pelo seu workspace ID real.
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.0-tts-flash",
        "prefix": "myvoice",
        "url": "https://your-audio-url.wav",
        "language_hints": ["en"],
        "enable_volume_normalization": "false"
    }
}'
modelstring(obrigatório)Modelo de clonagem de voz. Valores válidos:
  • voice-enrollment: Clonagem de voz Qwen-Audio-TTS/CosyVoice.
  • qwen-voice-enrollment: Clonagem de voz Qwen-TTS.
inputobject(obrigatório)Parâmetros de entrada.

Propriedades

action string(obrigatório)Tipo de ação.
  • Qwen-Audio-TTS/CosyVoice (voice-enrollment): Defina como create_voice.
  • Qwen (qwen-voice-enrollment): Defina como create.
target_model string(obrigatório)Modelo de texto para fala (TTS) que impulsiona a voz clonada. Deve corresponder ao modelo especificado na chamada à API TTS; caso contrário, a síntese falhará.url string(condicionalmente obrigatório)
Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando model é voice-enrollment).
URL do arquivo de áudio para clonagem de voz. A URL deve ser publicamente acessível.audio object(condicionalmente obrigatório)
Aplica-se apenas à clonagem de voz Qwen-TTS (quando model é qwen-voice-enrollment).
Dados de áudio. Dois métodos de envio são suportados:
  • Data URL (codificado em Base64): O formato é {"data": "data:{mime_type};base64,{base64_encoded_data}"}. Tipos MIME suportados: audio/wav, audio/mpeg e audio/mp4.
  • URL de áudio: O formato é {"data": "https://your-audio-url.wav"}. A URL deve ser publicamente acessível sem autenticação.
text string(opcional)
Aplica-se apenas à clonagem de voz Qwen-TTS (quando model é qwen-voice-enrollment).
Transcrição do áudio, utilizada para melhorar a qualidade da clonagem.prefix string(condicionalmente obrigatório)
Aplica-se apenas ao Qwen-Audio-TTS/CosyVoice (quando model é voice-enrollment).
Prefixo para o nome da voz. Apenas caracteres alfanuméricos são permitidos, com comprimento máximo de 10 caracteres. O nome final da voz segue este formato: {target_model}-{prefix}-{unique_id}.preferred_name string(condicionalmente obrigatório)
Aplica-se apenas à clonagem de voz Qwen-TTS (quando model é qwen-voice-enrollment).
Prefixo para o nome da voz. Apenas caracteres alfanuméricos e sublinhados são permitidos, com comprimento máximo de 16 caracteres.language_hints array[string](opcional)
Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando model é voice-enrollment). Suportado apenas por qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, v3-plus e v3-flash.
Auxilia 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"].language string(opcional)
Aplica-se apenas à clonagem de voz Qwen-TTS (quando model é qwen-voice-enrollment).
Idioma do áudio fornecido em audio.data. Ao utilizar este parâmetro, certifique-se de que o idioma especificado corresponde ao idioma real do áudio usado para clonagem.Valores válidos:
  • zh: Chinês
  • en: Inglês
  • de: Alemão
  • it: Italiano
  • pt: Português
  • es: Espanhol
  • ja: Japonês
  • ko: Coreano
  • fr: Francês
  • ru: Russo
Padrão: zh.max_prompt_audio_length float(opcional)
Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando model é voice-enrollment). Suportado apenas por 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 boolean(opcional)
Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando model é voice-enrollment). Suportado apenas por 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, preservando as características originais da voz.Padrão: false.enable_volume_normalization string(opcional)
Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice quando model está definido como voice-enrollment.
Define se o volume do áudio de amostra usado para clonagem de voz deve ser normalizado. Valores válidos:
  • "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 do áudio sintetizado com uma voz criada com este parâmetro desativado.Padrão: "false".

Corpo da resposta 

{
    "output": {
        "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
O Qwen-Audio-TTS/CosyVoice retorna o campo voice_id, enquanto o Qwen retorna o campo voice. A clonagem de voz Qwen-TTS também pode retornar os campos fallback_mode e fallback_reason.
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo.

Propriedades

voice_id / voicestringID da voz. O Qwen-Audio-TTS/CosyVoice retorna voice_id, enquanto o Qwen retorna voice. Utilize este valor diretamente no parâmetro de voz da API TTS.target_modelstring
Retornado apenas pelo Qwen.
Modelo TTS que impulsiona a voz clonada.fallback_modeboolean
Aplica-se apenas à clonagem de voz Qwen-TTS (quando model é qwen-voice-enrollment).
Indica se a voz foi criada em modo de fallback. Um valor true indica que a qualidade do áudio era baixa ou não correspondia ao texto fornecido, podendo reduzir a qualidade da clonagem.fallback_reasonstring
Retornado apenas quando fallback_mode é true.
Motivo do fallback. Os valores possíveis incluem no_merged_segments (não foi possível mesclar segmentos de áudio) e no_valid_asr_segments (incompatibilidade grave entre áudio e texto).
usageobjectInformações de uso desta solicitação.

Propriedades

count integerNúmero de vozes criadas. Sempre 1.

Consultar lista de vozes

Corpo da solicitação

Este exemplo utiliza o endpoint da região de Singapore. Para a região de Beijing, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Substitua {WorkspaceId} pelo seu workspace ID real.
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": "list_voice",
        "prefix": "myvoice",
        "page_size": 10,
        "page_index": 0
    }
}'
modelstring(obrigatório)Modelo de clonagem de voz. Valores válidos:
  • voice-enrollment: Clonagem de voz Qwen-Audio-TTS/CosyVoice.
  • qwen-voice-enrollment: Clonagem de voz Qwen-TTS.
inputobject(obrigatório)Parâmetros de entrada.

Propriedades

action string(obrigatório)Tipo de ação. Qwen-Audio-TTS/CosyVoice: list_voice. Qwen: list.prefix string(opcional)
Aplica-se apenas ao Qwen-Audio-TTS/CosyVoice.
Filtra vozes pelo prefixo do nome.page_index integer(opcional)Índice da página.page_size integer(opcional)Número de entradas por página.

Corpo da resposta 

{
    "output": {
        "voice_list": [
            {
                "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx",
                "gmt_create": "2024-12-11 13:38:02",
                "gmt_modified": "2024-12-11 13:38:02",
                "status": "OK"
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
O Qwen-Audio-TTS/CosyVoice retorna um array voice_list onde cada entrada contém o campo voice_id. O Qwen também retorna um array voice_list, mas cada entrada contém o campo voice. A saída do Qwen inclui adicionalmente os campos de paginação page_index, page_size e total_count.
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo.

Propriedades

page_indexinteger
Retornado apenas pelo Qwen.
Índice da página atual.page_sizeinteger
Retornado apenas pelo Qwen.
Número de entradas por página.total_countinteger
Retornado apenas pelo Qwen.
Número total de vozes.voice_listarray[object]Lista de vozes consultadas. Tanto o Qwen-Audio-TTS/CosyVoice quanto o Qwen usam o nome de campo voice_list.

Propriedades

voice_id / voicestringID da voz. O Qwen-Audio-TTS/CosyVoice usa voice_id, enquanto o Qwen usa voice.gmt_createstringHora de criação.gmt_modifiedstringHora da última modificação.statusstring
Retornado apenas pelo Qwen-Audio-TTS/CosyVoice.
Status da voz. Para valores válidos, consulte "Descrições de status de voz".target_modelstring
Retornado apenas pelo Qwen.
Modelo TTS que impulsiona a voz clonada.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerSempre 1 para Qwen-Audio-TTS/CosyVoice. Sempre 0 para Qwen.

Consultar detalhes da voz

Aplica-se apenas ao Qwen-Audio-TTS/CosyVoice (quando model é voice-enrollment). Os modelos Qwen não suportam a operação de consulta de detalhes da voz.

Corpo da solicitação

Este exemplo utiliza o endpoint da região de Singapore. Para a região de Beijing, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Substitua {WorkspaceId} pelo seu workspace ID real.
  • Qwen-Audio-TTS/CosyVoice
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": "query_voice",
        "voice_id": "yourVoiceId"
    }
}'
modelstring(obrigatório)Defina como voice-enrollment (Qwen-Audio-TTS/CosyVoice).
inputobject(obrigatório)Parâmetros de entrada.

Propriedades

action string(obrigatório)Defina como query_voice.voice_id string(obrigatório)ID da voz a ser consultada.

Corpo da resposta 

{
    "output": {
        "gmt_create": "2024-12-11 13:38:02",
        "resource_link": "https://yourAudioFileUrl",
        "target_model": "qwen-audio-3.0-tts-flash",
        "gmt_modified": "2024-12-11 13:38:02",
        "status": "OK"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo.

Propriedades

resource_linkstringURL do arquivo de áudio.gmt_createstringHora de criação.gmt_modifiedstringHora da última modificação.statusstringStatus da voz. Para valores válidos, consulte "Descrições de status de voz".target_modelstringModelo TTS que impulsiona a voz clonada.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerSempre 1.

Atualize uma voz

Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando model é voice-enrollment). Os modelos Qwen não suportam a operação de atualização.

Corpo da solicitação

Este exemplo utiliza o endpoint da região de Singapore. Para a região de Beijing, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.
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": "update_voice",
            "voice_id": "yourVoiceId",
            "url": "https://new-audio-url.wav"
        }
    }'
modelstring(obrigatório)Defina como voice-enrollment.
inputobject(obrigatório)Parâmetros de entrada.

Propriedades

action string(obrigatório)Defina como update_voice.voice_id string(obrigatório)ID da voz a ser atualizada.url string(obrigatório)URL do novo arquivo de áudio. A URL deve ser publicamente acessível.

Corpo da resposta 

{
    "output": {
        "preview_audio": {}
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo. A operação de atualização não retorna dados comerciais. A resposta pode incluir um campo preview_audio, que é um objeto vazio e pode ser ignorado.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerSempre 1.

Exclua uma voz

Corpo da solicitação

Este exemplo utiliza o endpoint da região de Singapore. Para a região de Beijing, use: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Substitua {WorkspaceId} pelo seu workspace ID real.
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": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'
modelstring(obrigatório)Modelo de clonagem de voz. Valores válidos:
  • voice-enrollment: Clonagem de voz Qwen-Audio-TTS/CosyVoice.
  • qwen-voice-enrollment: Clonagem de voz Qwen-TTS.
inputobject(obrigatório)Parâmetros de entrada.

Propriedades

action string(obrigatório)Tipo de ação. Qwen-Audio-TTS/CosyVoice: delete_voice. Qwen: delete.voice_id string(condicionalmente obrigatório)
Aplica-se apenas ao Qwen-Audio-TTS/CosyVoice.
ID da voz a ser excluída.voice string(condicionalmente obrigatório)
Aplica-se apenas ao Qwen.
Nome da voz a ser excluída.

Corpo da resposta 

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
O Qwen-Audio-TTS/CosyVoice retorna um objeto de saída vazio, enquanto o Qwen retorna o campo voice com o nome da voz excluída.
request_idstringIdentificador exclusivo desta solicitação.
outputobjectDados retornados pelo modelo. O Qwen-Audio-TTS/CosyVoice retorna um objeto vazio, enquanto o Qwen retorna o nome da voz excluída.

Propriedades

voicestring
Retornado apenas pelo Qwen.
Nome da voz excluída.
usageobjectInformações de uso desta solicitação.

Propriedades

count integerSempre 1 para Qwen-Audio-TTS/CosyVoice. Sempre 0 para Qwen.

Descrições de status de voz

Após a criação, a voz passa por um processo de revisão. Os status abaixo aplicam-se apenas ao Qwen-Audio-TTS/CosyVoice (quando model é voice-enrollment). As respostas de consulta e listagem do Qwen não incluem um campo de status.

Status

Descrição

DEPLOYING

Em revisão ou processamento.

OK

Revisão aprovada. A voz está pronta para uso.

UNDEPLOYED

Revisão rejeitada. A voz não pode ser usada.

Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais