Voice cloning HTTP API reference - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

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

Guia do usuário: Voice cloning.

Endpoint do service

Singapore

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization

Substitua {WorkspaceId} pelo seu workspace ID real.

China (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization

Substitua {WorkspaceId} pelo seu workspace ID real.

ImportanteO 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.

Clonagem de voz 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": "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"
    }
}'

Clonagem de voz Qwen-TTS

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": "qwen-voice-enrollment",
    "input": {
        "action": "create",
        "target_model": "qwen3-tts-vc-realtime-2026-01-15",
        "preferred_name": "myvoice",
        "audio": {"data": "data:audio/mpeg;base64,{base64_encoded_audio}"}
    }
}'

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)

ImportanteAplica-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)

ImportanteAplica-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)

ImportanteAplica-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)

ImportanteAplica-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)

ImportanteAplica-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)

ImportanteAplica-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)

ImportanteAplica-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)

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)

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)

ImportanteAplica-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

Clonagem de voz Qwen-Audio-TTS/CosyVoice

{
    "output": {
        "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Clonagem de voz Qwen-TTS

{
    "output": {
        "voice": "yourVoice",
        "target_model": "qwen3-tts-vc-realtime-2026-01-15"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

ImportanteO 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_idstring

Identificador exclusivo desta solicitação.

outputobject

Dados retornados pelo modelo.

Propriedades

voice_id / voicestring

ID 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

ImportanteRetornado apenas pelo Qwen.

Modelo TTS que impulsiona a voz clonada.

fallback_modeboolean

ImportanteAplica-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

ImportanteRetornado 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).

usageobject

Informações de uso desta solicitação.

Propriedades

count integer

Nú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.

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": "list_voice",
        "prefix": "myvoice",
        "page_size": 10,
        "page_index": 0
    }
}'

Clonagem de voz Qwen-TTS

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": "qwen-voice-enrollment",
    "input": {
        "action": "list",
        "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)

ImportanteAplica-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

Qwen-Audio-TTS/CosyVoice

{
    "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"
}

Qwen

{
    "output": {
        "page_index": 0,
        "page_size": 10,
        "total_count": 2,
        "voice_list": [
            {
                "voice": "yourVoice1",
                "gmt_create": "2025-08-11 17:59:32",
                "gmt_modified": "2025-08-11 17:59:32",
                "language": "en",
                "target_model": "qwen3-tts-vc-realtime-2026-01-15"
            }
        ]
    },
    "usage": {
        "count": 0
    },
    "request_id": "xxxx-xxxx-xxxx"
}

ImportanteO 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_idstring

Identificador exclusivo desta solicitação.

outputobject

Dados retornados pelo modelo.

Propriedades

page_indexinteger

ImportanteRetornado apenas pelo Qwen.

Índice da página atual.

page_sizeinteger

ImportanteRetornado apenas pelo Qwen.

Número de entradas por página.

total_countinteger

ImportanteRetornado 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 / voicestring

ID da voz. O Qwen-Audio-TTS/CosyVoice usa voice_id, enquanto o Qwen usa voice.

gmt_createstring

Hora de criação.

gmt_modifiedstring

Hora da última modificação.

statusstring

ImportanteRetornado apenas pelo Qwen-Audio-TTS/CosyVoice.

Status da voz. Para valores válidos, consulte "Descrições de status de voz".

target_modelstring

ImportanteRetornado apenas pelo Qwen.

Modelo TTS que impulsiona a voz clonada.

usageobject

Informações de uso desta solicitação.

Propriedades

count integer

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

Consultar detalhes da voz

ImportanteAplica-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_idstring

Identificador exclusivo desta solicitação.

outputobject

Dados retornados pelo modelo.

Propriedades

resource_linkstring

URL do arquivo de áudio.

gmt_createstring

Hora de criação.

gmt_modifiedstring

Hora da última modificação.

statusstring

Status da voz. Para valores válidos, consulte "Descrições de status de voz".

target_modelstring

Modelo TTS que impulsiona a voz clonada.

usageobject

Informações de uso desta solicitação.

Propriedades

count integer

Sempre 1.

Atualize uma voz

ImportanteAplica-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_idstring

Identificador exclusivo desta solicitação.

outputobject

Dados 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.

usageobject

Informações de uso desta solicitação.

Propriedades

count integer

Sempre 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.

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": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'

Clonagem de voz Qwen-TTS

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": "qwen-voice-enrollment",
    "input": {
        "action": "delete",
        "voice": "yourVoice"
    }
}'

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)

ImportanteAplica-se apenas ao Qwen-Audio-TTS/CosyVoice.

ID da voz a ser excluída.

voice string(condicionalmente obrigatório)

ImportanteAplica-se apenas ao Qwen.

Nome da voz a ser excluída.

Corpo da resposta

Qwen-Audio-TTS/CosyVoice

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Qwen

{
    "output": {
        "voice": "yourVoice"
    },
    "usage": {
        "count": 0
    },
    "request_id": "xxxx-xxxx-xxxx"
}

ImportanteO 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_idstring

Identificador exclusivo desta solicitação.

outputobject

Dados retornados pelo modelo. O Qwen-Audio-TTS/CosyVoice retorna um objeto vazio, enquanto o Qwen retorna o nome da voz excluída.

Propriedades

voicestring

ImportanteRetornado apenas pelo Qwen.

Nome da voz excluída.

usageobject

Informações de uso desta solicitação.

Propriedades

count integer

Sempre 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.