Référence du SDK Java pour le clonage vocal - DashScope - Alibaba Cloud Model Studio

Utilisez le SDK Java DashScope pour cloner et gérer les voix Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice.

Endpoint du service

Le SDK utilise l'endpoint China (Beijing) par défaut. Pour changer de région, modifiez Constants.baseHttpApiUrl avant l'initialisation.

Remarque

Les clés API varient selon la région. Utilisez la clé API de la région cible.
Le paramètre de région est global et affecte tous les appels d’API du SDK DashScope.

Singapore

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

Remplacez {WorkspaceId} par votre ID d'espace de travail.

China (Beijing)

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

Remplacez {WorkspaceId} par votre ID d'espace de travail.

ImportantAlibaba Cloud Model Studio a publié des domaines spécifiques aux espaces de travail pour les régions China (Beijing) et Singapore. Ces nouveaux domaines dédiés offrent des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :

China (Beijing) : de dashscope.aliyuncs.com vers {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore : de dashscope-intl.aliyuncs.com vers {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Classe VoiceEnrollmentService

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

Objectif: Gère le cycle de vie des voix clonées Qwen-Audio-TTS, Qwen-Audio-Realtime et CosyVoice (création, consultation, mise à jour et suppression).

Constructeur

public VoiceEnrollmentService(String apiKey)

Paramètres :

Paramètre	Type	Description
apiKey	String	Clé API

createVoice() - Créer une voix

Signature de la méthode :

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

Paramètres :

Paramètre	Type	Obligatoire	Description
targetModel	String	Oui	Modèle cible qui utilise la voix. Il doit correspondre au modèle utilisé dans les requêtes ultérieures avec cette voix, sinon les requêtes échouent.
prefix	String	Oui	Préfixe du nom de la voix. Seuls les caractères alphanumériques sont autorisés, avec une longueur maximale de 10 caractères. Le nom de voix résultant suit ce format : `{target_model}-{prefix}-{unique_id}`.
url	String	Oui	Audio de référence pour le clonage vocal. Accepte une URL accessible publiquement ou un Data URI encodé en Base64, par exemple `data:audio/wav;base64,...`.
customParam	VoiceEnrollmentParam	Non	Paramètres personnalisés tels que languageHints et maxPromptAudioLength.

Valeur de retour : Un objet Voice. Appelez getVoiceId() pour récupérer l'ID de la voix.

listVoice() - Lister les voix

Signature de la méthode :

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

Paramètres :

Paramètre	Type	Obligatoire	Description
prefix	String	Non	Filtre les voix par préfixe de nom.
pageIndex	int	Non	Index de page, commençant à 0.
pageSize	int	Non	Nombre d'enregistrements par page.

Valeur de retour : Un tableau Voice[].

queryVoice() - Récupérer les détails d'une voix

Signature de la méthode :

public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Paramètres :

Paramètre	Type	Obligatoire	Description
voiceId	String	Oui	ID de la voix à récupérer.

Valeur de retour : Un objet Voice contenant les détails de la voix.

updateVoice() - Mettre à jour une voix

Signatures de la méthode :

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

Paramètres :

Paramètre	Type	Obligatoire	Description
voiceId	String	Oui	ID de la voix à mettre à jour.
url	String	Oui	Nouvel audio de référence. Accepte une URL accessible publiquement ou un Data URI encodé en Base64, par exemple `data:audio/wav;base64,...`.
customParam	VoiceEnrollmentParam	Non	Paramètres personnalisés.

deleteVoice() - Supprimer une voix

Signature de la méthode :

public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Paramètres :

Paramètre	Type	Obligatoire	Description
voiceId	String	Oui	ID de la voix à supprimer.

Classe VoiceEnrollmentParam

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

Construisez les objets de paramètres à l'aide du modèle builder.

Méthode	Type	Description
model(String)	String	Modèle de clonage vocal. La valeur doit être « voice-enrollment ».
languageHints(List<String>)	List<String>	Aide le modèle à identifier la langue de l'échantillon audio afin d'extraire les caractéristiques vocales plus précisément et d'améliorer la qualité du clonage. Si la langue spécifiée ne correspond pas à la langue réelle de l'audio (par exemple, définir `en` alors que l'audio est en chinois), le système ignore cette valeur et détecte automatiquement la langue. Ce paramètre est un tableau qui doit contenir exactement un élément. RemarqueS’applique à 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. Cliquez pour voir les langues prises en charge par modèle 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 : Chinois en : Anglais fr : Français de : Allemand ja : Japonais ko : Coréen ru : Russe pt : Portugais th : Thaï id : Indonésien vi : Vietnamien it : Italien es : Espagnol ms : Malaisien fil : Filipino ar : Arabe cosyvoice-v3-plus : zh : Chinois en : Anglais fr : Français de : Allemand ja : Japonais ko : Coréen ru : Russe cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash : zh : Chinois en : Anglais fr : Français de : Allemand ja : Japonais ko : Coréen ru : Russe pt : Portugais th : Thaï id : Indonésien vi : Vietnamien Par défaut : ["zh"].
maxPromptAudioLength(Float)	Float	Durée maximale (en secondes) de l'audio de référence après prétraitement. Valeurs valides : [3,0, 30,0]. Par défaut : 10,0. RemarqueS’applique à 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	Définit des paramètres personnalisés, tels que parameter("language_hints", Arrays.asList("en")), parameter("max_prompt_audio_length", 10.0f), parameter("enable_preprocess", false) et parameter("enable_volume_normalization", "false").

Paramètres supplémentaires

Paramètre Type Obligatoire Description

Paramètre	Type	Obligatoire	Description
enable_preprocess	boolean	Non	Indique s'il faut activer le prétraitement audio (réduction du bruit, amélioration audio et normalisation du volume). Activez cette option pour les enregistrements comportant du bruit de fond. Désactivez-la pour les enregistrements réalisés dans des environnements calmes afin de préserver les caractéristiques vocales originales. Par défaut : false. RemarqueS’applique à 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	Non	Indique s'il faut normaliser le volume de l'échantillon audio utilisé pour le clonage vocal. Les valeurs valides sont `"true"` et `"false"`. Lorsque cette option est activée, l'audio synthétisé avec la voix créée peut avoir un volume différent de celui synthétisé avec une voix créée sans ce paramètre. Par défaut : `"false"`.

enable_preprocess

boolean

Non

Indique s'il faut activer le prétraitement audio (réduction du bruit, amélioration audio et normalisation du volume). Activez cette option pour les enregistrements comportant du bruit de fond. Désactivez-la pour les enregistrements réalisés dans des environnements calmes afin de préserver les caractéristiques vocales originales.

Par défaut : false.

RemarqueS’applique à 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

Non

Indique s'il faut normaliser le volume de l'échantillon audio utilisé pour le clonage vocal. Les valeurs valides sont "true" et "false". Lorsque cette option est activée, l'audio synthétisé avec la voix créée peut avoir un volume différent de celui synthétisé avec une voix créée sans ce paramètre. Par défaut : "false".

Exemples de code

Créer une voix

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

Pour un fichier WAV local, ajoutez l’affectation suivante dans le bloc try ci-dessus, avant l’appel à createVoice. Pour mettre à jour une voix, transmettez également le Data URI dans le paramètre url de updateVoice. Remplacez sample.wav par le chemin de votre fichier audio local.

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

Lister les voix

Cet exemple nécessite la bibliothèque tierce 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));
    }
}

Récupérer une voix spécifique

Cet exemple nécessite la bibliothèque tierce 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));
    }
}

Mettre à jour une voix

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

Supprimer une voix

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