Referencia del SDK de Java para clonación de voz - DashScope - Alibaba Cloud Model Studio

Utilice el SDK de Java de DashScope para clonar y gestionar voces de Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice.

Endpoint de servicio

El SDK utiliza el endpoint de China (Beijing) de forma predeterminada. Para cambiar a una región diferente, modifique Constants.baseHttpApiUrl antes de la inicialización.

Nota

Las API keys varían por región. Use la API key de la región de destino.
La configuración de región es global y afecta a todas las llamadas de API del SDK de DashScope.

Singapore

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

China (Beijing)

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

ImportanteAlibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Beijing) y Singapur. Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:

China (Pekín): de dashscope.aliyuncs.com a {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapur: de dashscope-intl.aliyuncs.com a {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Clase VoiceEnrollmentService

Paquete: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService

Propósito: Administra el ciclo de vida de las voces clonadas de Qwen-Audio-TTS, Qwen-Audio-Realtime y CosyVoice (crear, consultar, actualizar y eliminar).

Constructor

public VoiceEnrollmentService(String apiKey)

Parámetros:

Parámetro	Tipo	Descripción
apiKey	String	Clave de API

createVoice() - Crear una voz

Firma del método:

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

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
targetModel	String	Sí	Modelo de destino que usa la voz. Debe coincidir con el modelo usado en las solicitudes posteriores con esta voz; de lo contrario, las solicitudes fallan.
prefix	String	Sí	Un prefijo para el nombre de la voz. Solo se permiten caracteres alfanuméricos, con una longitud máxima de 10 caracteres. El nombre de voz resultante sigue este formato: `{target_model}-{prefix}-{unique_id}`.
url	String	Sí	Audio de referencia para la clonación de voz. Acepta una URL de acceso público o un Data URI codificado en Base64, por ejemplo, `data:audio/wav;base64,...`.
customParam	VoiceEnrollmentParam	No	Parámetros personalizados como languageHints y maxPromptAudioLength.

Valor de retorno: Un objeto Voice. Llame a getVoiceId() para recuperar el ID de la voz.

listVoice() - Listar voces

Firma del método:

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

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
prefix	String	No	Filtra las voces por prefijo de nombre.
pageIndex	int	No	Índice de página, comenzando desde 0.
pageSize	int	No	Número de registros por página.

Valor de retorno: Un arreglo Voice[].

queryVoice() - Recuperar detalles de la voz

Firma del método:

public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
voiceId	String	Sí	El ID de la voz a recuperar.

Valor de retorno: Un objeto Voice que contiene los detalles de la voz.

updateVoice() - Actualizar una voz

Firmas de 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:

Parámetro	Tipo	Obligatorio	Descripción
voiceId	String	Sí	El ID de voz a actualizar.
url	String	Sí	Nuevo audio de referencia. Acepta una URL de acceso público o un Data URI codificado en Base64, por ejemplo, `data:audio/wav;base64,...`.
customParam	VoiceEnrollmentParam	No	Parámetros personalizados.

deleteVoice() - Eliminar una voz

Firma del método:

public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Parámetros:

Parámetro	Tipo	Obligatorio	Descripción
voiceId	String	Sí	El ID de voz a eliminar.

Clase VoiceEnrollmentParam

Paquete: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam

Construya objetos de parámetros utilizando el patrón builder.

Método	Tipo	Descripción
model(String)	String	El modelo de clonación de voz. El valor debe ser "voice-enrollment".
`languageHints(List<String>)`	`List<String>`	Ayuda al modelo a identificar el idioma del audio de muestra para extraer características de voz con mayor precisión y mejorar la calidad de la clonación. Si el idioma especificado no coincide con el idioma real del audio (por ejemplo, establecer `en` cuando el audio está en chino), el sistema ignora este valor y detecta el idioma automáticamente. Este parámetro es una matriz y debe contener exactamente un elemento. NotaSe aplica 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. Haga clic para ver los idiomas compatibles por modelo 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: Chino en: Inglés fr: Francés de: Alemán ja: Japonés ko: Coreano ru: Ruso pt: Portugués th: Tailandés id: Indonesio vi: Vietnamita it: Italiano es: Español ms: Malayo fil: Filipino ar: Árabe cosyvoice-v3-plus: zh: Chino en: Inglés fr: Francés de: Alemán ja: Japonés ko: Coreano ru: Ruso cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: zh: Chino en: Inglés fr: Francés de: Alemán ja: Japonés ko: Coreano ru: Ruso pt: Portugués th: Tailandés id: Indonesio vi: Vietnamita Valor predeterminado: ["zh"].
maxPromptAudioLength(Float)	Float	La duración máxima (en segundos) del audio de referencia después del preprocesamiento. Valores válidos: [3.0, 30.0]. Predeterminado: 10.0. NotaSe aplica 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)	Object	Establece parámetros personalizados, como parameter("language_hints", Arrays.asList("en")), parameter("max_prompt_audio_length", 10.0f), parameter("enable_preprocess", false) y parameter("enable_volume_normalization", "false").

Parámetros adicionales

Parámetro Tipo Obligatorio Descripción

Parámetro	Tipo	Obligatorio	Descripción
enable_preprocess	boolean	No	Indica si se debe habilitar el preprocesamiento de audio (reducción de ruido, mejora de audio y normalización de volumen). Habilite esta opción para grabaciones con ruido de fondo. Desactívela para grabaciones en entornos silenciosos para preservar las características originales de la voz. Predeterminado: false. NotaSe aplica 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_normalization	String	No	Indica si se debe normalizar el volumen del audio de muestra utilizado para la clonación de voz. Los valores válidos son `"true"` y `"false"`. Cuando está habilitado, el audio sintetizado con la voz creada puede tener un volumen diferente al del audio sintetizado con una voz creada con este parámetro deshabilitado. Valor predeterminado: `"false"`.

enable_preprocess

boolean

Indica si se debe habilitar el preprocesamiento de audio (reducción de ruido, mejora de audio y normalización de volumen). Habilite esta opción para grabaciones con ruido de fondo. Desactívela para grabaciones en entornos silenciosos para preservar las características originales de la voz.

Predeterminado: false.

NotaSe aplica 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_normalization

String

Indica si se debe normalizar el volumen del audio de muestra utilizado para la clonación de voz. Los valores válidos son "true" y "false". Cuando está habilitado, el audio sintetizado con la voz creada puede tener un volumen diferente al del audio sintetizado con una voz creada con este parámetro deshabilitado. Valor predeterminado: "false".

Código de ejemplo

Crear una 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);
        }
    }
}

Para un archivo WAV local, agregue la siguiente asignación dentro del bloque try anterior, antes de llamar a createVoice. Para actualizar una voz, pase también el Data URI mediante el parámetro url de updateVoice. Sustituya sample.wav por la ruta de su archivo de audio local.

fileUrl = "data:audio/wav;base64," + java.util.Base64.getEncoder().encodeToString(
        java.nio.file.Files.readAllBytes(java.nio.file.Paths.get("sample.wav")));

Listar voces

Este ejemplo requiere la biblioteca de terceros 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 una voz específica

Este ejemplo requiere la biblioteca de terceros 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));
    }
}

Actualizar una 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());
    }
}

Eliminar una 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());
    }
}