Skip to main content

Referência do SDK Java de clonagem de voz do Qwen-Audio e CosyVoice

Clone e gerencie vozes do Qwen-Audio e CosyVoice com o SDK Java do DashScope.

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.
  • As API keys variam por região. Use a API key da região de destino.
  • A configuração de região é global e afeta todas as chamadas de API do SDK DashScope.
  • Singapore
  • China (Beijing)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Substitua {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 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

Classe VoiceEnrollmentService

Pacote: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService Finalidade: Gerencia o ciclo de vida das vozes clonadas Qwen-Audio-TTS, Qwen-Audio-Realtime e CosyVoice (criar, consultar, atualizar e excluir).

Construtor

public VoiceEnrollmentService(String apiKey)
Parâmetros:
ParameterTypeDescription
apiKeyStringChave 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:
ParameterTypeRequiredDescription
targetModelStringYesModelo 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.
prefixStringYesPrefixo 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}.
urlStringYesÁ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,....
customParamVoiceEnrollmentParamNoParâ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:
ParameterTypeRequiredDescription
prefixStringNoFiltra vozes pelo prefixo do nome.
pageIndexintNoÍndice da página, começando em 0.
pageSizeintNoQuantidade de registros por página.
Valor de retorno: Array Voice[]. Se getTargetModel() retornar null para um item da lista, leia o ID do modelo de destino em voice.getData().get("target_model").

queryVoice() - Recuperar detalhes da voz

Assinatura do método:
public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException
Parâmetros:
ParameterTypeRequiredDescription
voiceIdStringYesID da voz a recuperar.
Valor de retorno: Objeto Voice com os detalhes da voz. Use getTargetModel() para obter o ID do modelo de destino.

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:
ParameterTypeRequiredDescription
voiceIdStringYesID da voz a atualizar.
urlStringYesNovo áudio de referência. Aceita uma URL acessível publicamente ou um Data URI codificado em Base64, como data:audio/wav;base64,....
customParamVoiceEnrollmentParamNoParâmetros personalizados.

deleteVoice() - Excluir uma voz

Assinatura do método:
public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException
Parâmetros:
ParameterTypeRequiredDescription
voiceIdStringYesID da voz a excluir.

Classe VoiceEnrollmentParam

Pacote: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam Crie objetos de parâmetro usando o padrão builder.
MethodTypeDescription
model(String)StringModelo de clonagem de voz. O valor deve ser "voice-enrollment".
languageHints(List<String>)List<String>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.
  • 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:
    • 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)FloatDuraçã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.
parameter(String, Object)ObjectDefine 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

ParameterTypeRequiredDescription
enable_preprocessbooleanNoIndica 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.
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_normalizationStringNoDefine 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.1-tts-plus";
        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);
        }
    }
}
Para um arquivo WAV local, adicione a atribuição a seguir dentro do bloco try acima, antes de chamar createVoice. Para atualizar uma voz, passe também o Data URI pelo parâmetro url de updateVoice. Substitua sample.wav pelo caminho do seu arquivo de áudio local.
fileUrl = "data:audio/wav;base64," + java.util.Base64.getEncoder().encodeToString(
        java.nio.file.Files.readAllBytes(java.nio.file.Paths.get("sample.wav")));

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));
        for (Voice voice : voices) {
            logger.info("Modelo de destino: {}", voice.getData().get("target_model"));
        }
    }
}

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.1-tts-plus-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));
        logger.info("Modelo de destino: {}", voice.getTargetModel());
    }
}

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.1-tts-plus-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.1-tts-plus-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());
    }
}