Copy

Guia do usuário: Voice cloning.

Endpoint do service

O SDK usa o endpoint da região China (Beijing) por padrão. Para mudar para outra região, modifique Constants.baseHttpApiUrl antes da inicialização.

Singapore
China (Beijing)

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Substitua {WorkspaceId} pelo seu workspace ID real.

Mudar para a região Singapore:

import com.alibaba.dashscope.utils.Constants;

// Set at the beginning of your code
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

Note :

As chaves de API variam conforme a região. Use a chave correspondente à região de destino.

A configuração de região é global e afeta todas as chamadas de API do DashScope SDK.

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:

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.

Classe VoiceEnrollmentService

Pacote: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService Finalidade: Gerencia o ciclo de vida das vozes clonadas Qwen-Audio-TTS/CosyVoice (criação, listagem, recuperação, atualização e exclusão).

Construtor

public VoiceEnrollmentService(String apiKey)

Parâmetros:

Parameter	Type	Description
apiKey	String	Chave de API

createVoice() - Criar uma voz

Assinatura do método:

public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException

Parâmetros:

Parameter	Type	Required	Description
targetModel	String	Yes	Modelo de text-to-speech (TTS) que aciona a voz clonada. Deve corresponder ao modelo especificado na chamada da API TTS; caso contrário, a síntese falhará.
prefix	String	Yes	Prefixo para o 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	String	Yes	URL do arquivo de áudio para clonagem de voz. A URL deve ser acessível publicamente.
customParam	VoiceEnrollmentParam	No	Parâmetros personalizados como languageHints e maxPromptAudioLength.

Valor de retorno: Objeto Voice. Chame getVoiceId() para obter o ID da voz.

listVoice() - Listar vozes

Assinatura do método:

public Voice[] listVoice(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException

Parâmetros:

Parameter	Type	Required	Description
prefix	String	No	Filtra vozes pelo prefixo do nome.
pageIndex	int	No	Índice da página, começando em 0.
pageSize	int	No	Quantidade de registros por página.

Valor de retorno: Array Voice[].

queryVoice() - Recuperar detalhes da voz

Assinatura do método:

public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Parâmetros:

Parameter	Type	Required	Description
voiceId	String	Yes	ID da voz a recuperar.

Valor de retorno: Objeto Voice com os detalhes da voz.

updateVoice() - Atualizar uma voz

Assinaturas dos métodos:

public void updateVoice(String voiceId, String url) throws NoApiKeyException, InputRequiredException
public void updateVoice(String voiceId, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException

Parâmetros:

Parameter	Type	Required	Description
voiceId	String	Yes	ID da voz a atualizar.
url	String	Yes	Nova URL do arquivo de áudio.
customParam	VoiceEnrollmentParam	No	Parâmetros personalizados.

deleteVoice() - Excluir uma voz

Assinatura do método:

public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Parâmetros:

Parameter	Type	Required	Description
voiceId	String	Yes	ID da voz a excluir.

Classe VoiceEnrollmentParam

Pacote: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam Crie objetos de parâmetro usando o padrão builder.

Method	Type	Description
model(String)	String	Modelo de clonagem de voz. O valor deve ser "voice-enrollment".
languageHints(List<String>)	List<String>	Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando o modelo é `voice-enrollment`). Compatível somente com qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, v3-plus e v3-flash. 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, 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"].
maxPromptAudioLength(Float)	Float	Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando o modelo é `voice-enrollment`). Compatível somente com 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.
parameter(String, Object)	Object	Define parâmetros personalizados, como parameter("language_hints", Arrays.asList("en")), parameter("max_prompt_audio_length", 10.0f), parameter("enable_preprocess", false) e parameter("enable_volume_normalization", "false").

Parâmetros adicionais

Parameter	Type	Required	Description
enable_preprocess	boolean	No	Aplica-se apenas à clonagem de voz Qwen-Audio-TTS/CosyVoice (quando o modelo é `voice-enrollment`). Compatível somente com qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash e v3-flash. Indica 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 preservar as características originais da voz. Padrão: false.
enable_volume_normalization	String	No	Define se o volume do áudio de amostra usado na clonagem de voz será normalizado. Os valores válidos são `"true"` e `"false"`. Quando ativado, o áudio sintetizado com a voz criada pode ter volume diferente daquele sintetizado com uma voz criada com este parâmetro desativado. Padrão: `"false"`.

Código de exemplo

Criar uma voz

import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.utils.Constants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.Arrays;

public class Main {
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args) {
        // The following uses the Singapore region. Replace {WorkspaceId} with your actual workspace ID. For other regions, modify the URL accordingly.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        String targetModel = "qwen-audio-3.0-tts-flash";
        String prefix = "myvoice";
        String fileUrl = "https://your-audio-file-url";
        String cloneModelName = "voice-enrollment";

        try {
            VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
            Voice myVoice = service.createVoice(
                    targetModel,
                    prefix,
                    fileUrl,
                    VoiceEnrollmentParam.builder()
                            .model(cloneModelName)
                            .parameter("language_hints", Arrays.asList("en"))
                            // .parameter("max_prompt_audio_length", 10.0f)
                            // .parameter("enable_preprocess", false)
                            // .parameter("enable_volume_normalization", "false")
                            .build());

            logger.info("Voice creation submitted. Request ID: {}", service.getLastRequestId());
            logger.info("Generated Voice ID: {}", myVoice.getVoiceId());
        } catch (Exception e) {
            logger.error("Failed to create voice", e);
        }
    }
}

Listar vozes

Este exemplo requer a biblioteca de terceiros com.google.gson.Gson.

import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Replace with your API key if not using an environment variable
    private static String prefix = "myvoice"; // Replace with your actual value
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // The following uses the Singapore region. Replace {WorkspaceId} with your actual workspace ID. For other regions, modify the URL accordingly.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // List voices
        Voice[] voices = service.listVoice(prefix, 0, 10);
        logger.info("List successful. Request ID: {}", service.getLastRequestId());
        logger.info("Voices Details: {}", new Gson().toJson(voices));
    }
}

Recuperar uma voz específica

Este exemplo requer a biblioteca de terceiros com.google.gson.Gson.

import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Replace with your API key if not using an environment variable
    private static String voiceId = "qwen-audio-3.0-tts-flash-myvoice-xxx"; // Replace with your actual value
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // The following uses the Singapore region. Replace {WorkspaceId} with your actual workspace ID. For other regions, modify the URL accordingly.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        Voice voice = service.queryVoice(voiceId);

        logger.info("Query successful. Request ID: {}", service.getLastRequestId());
        logger.info("Voice Details: {}", new Gson().toJson(voice));
    }
}

Atualizar uma voz

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Replace with your API key if not using an environment variable
    private static String fileUrl = "https://your-audio-file-url";  // Replace with your actual value
    private static String voiceId = "qwen-audio-3.0-tts-flash-myvoice-xxx"; // Replace with your actual value
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // The following uses the Singapore region. Replace {WorkspaceId} with your actual workspace ID. For other regions, modify the URL accordingly.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Update the voice
        service.updateVoice(voiceId, fileUrl);
        logger.info("Update submitted. Request ID: {}", service.getLastRequestId());
    }
}

Excluir uma voz

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Replace with your API key if not using an environment variable
    private static String voiceId = "qwen-audio-3.0-tts-flash-myvoice-xxx"; // Replace with your actual value
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // The following uses the Singapore region. Replace {WorkspaceId} with your actual workspace ID. For other regions, modify the URL accordingly.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Delete the voice
        service.deleteVoice(voiceId);
        logger.info("Deletion submitted. Request ID: {}", service.getLastRequestId());
    }
}

​Endpoint do service

​Classe VoiceEnrollmentService

​Construtor

​createVoice() - Criar uma voz

​listVoice() - Listar vozes

​queryVoice() - Recuperar detalhes da voz

​updateVoice() - Atualizar uma voz

​deleteVoice() - Excluir uma voz

​Classe VoiceEnrollmentParam

​Parâmetros adicionais

​Código de exemplo

​Criar uma voz

​Listar vozes

​Recuperar uma voz específica

​Atualizar uma voz

​Excluir uma voz

Endpoint do service

Classe VoiceEnrollmentService

Construtor

createVoice() - Criar uma voz

listVoice() - Listar vozes

queryVoice() - Recuperar detalhes da voz

updateVoice() - Atualizar uma voz

deleteVoice() - Excluir uma voz

Classe VoiceEnrollmentParam

Parâmetros adicionais

Código de exemplo

Criar uma voz

Listar vozes

Recuperar uma voz específica

Atualizar uma voz

Excluir uma voz