Voice cloning Java SDK reference

Use the DashScope Java SDK to clone and manage CosyVoice voices. User guide: Voice cloning.

Service endpoint

The SDK uses the China (Beijing) endpoint by default. To switch to a different region, modify Constants.baseHttpApiUrl before initialization.

International

If you select the International deployment scope, model inference compute resources are dynamically scheduled worldwide, excluding the Chinese mainland. Static data is stored in your selected region. Supported region: Singapore.

https://dashscope-intl.aliyuncs.com/api/v1

Chinese mainland

If you select the Chinese mainland deployment scope, model inference compute resources are restricted to the Chinese mainland. Static data is stored in your selected region. Supported region: China (Beijing).

https://dashscope.aliyuncs.com/api/v1

Switch to the Singapore region:

HELPCODEESCAPE-java
import com.alibaba.dashscope.common.Constants;

// Set at the beginning of your code
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

Note :

API keys differ between regions. Use the API key that corresponds to the target region.
The region setting is global and affects all DashScope SDK API calls.

VoiceEnrollmentService class

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

Purpose: Manages the lifecycle of CosyVoice cloned voices (create, list, retrieve, update, and delete).

Constructor

HELPCODEESCAPE-java
public VoiceEnrollmentService(String apiKey)

Parameters:

Parameter	Type	Description
apiKey	String	API key

createVoice() - Create a voice

Method signature:

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

Parameters:

Parameter	Type	Required	Description
targetModel	String	Yes	The text-to-speech (TTS) model that drives the cloned voice. It must match the model you specify when calling the TTS API; otherwise, synthesis fails.
prefix	String	Yes	A prefix for the voice name. Only alphanumeric characters are allowed, with a maximum length of 10 characters. The resulting voice name follows this format: `{target_model}-{prefix}-{unique_id}`.
url	String	Yes	The URL of the audio file for voice cloning. The URL must be publicly accessible.
customParam	VoiceEnrollmentParam	No	Custom parameters such as languageHints and maxPromptAudioLength.

Return value : A Voice object. Call getVoiceId() to retrieve the voice ID.

listVoice() - List voices

Method signature:

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

Parameters:

Parameter	Type	Required	Description
prefix	String	No	Filters voices by name prefix.
pageIndex	int	No	Page index, starting from 0.
pageSize	int	No	Number of records per page.

Return value : A Voice[] array.

queryVoice() - Retrieve voice details

Method signature:

HELPCODEESCAPE-java
public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Parameters:

Parameter	Type	Required	Description
voiceId	String	Yes	The ID of the voice to retrieve.

Return value : A Voice object containing the voice details.

updateVoice() - Update a voice

Method signature:

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

Parameters:

Parameter	Type	Required	Description
voiceId	String	Yes	The voice ID to update.
url	String	Yes	The new audio file URL.
customParam	VoiceEnrollmentParam	No	Custom parameters.

deleteVoice() - Delete a voice

Method signature:

HELPCODEESCAPE-java
public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Parameters:

Parameter	Type	Required	Description
voiceId	String	Yes	The voice ID to delete.

VoiceEnrollmentParam class

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

Build parameter objects using the builder pattern.

Method	Type	Description
model(String)	String	The voice cloning model. The value must be "voice-enrollment".
languageHints(List )	List	Important ** Applies only to CosyVoice voice cloning (when model is `voice-enrollment`). Supported only by cosyvoice-v3.5-plus, v3.5-flash, v3-plus, and v3-flash. Helps the model identify the language of the sample audio to extract voice features more accurately and improve cloning quality. If the specified language doesn't match the actual audio language (for example, setting `en` when the audio is in Chinese), the system ignores this value and detects the language automatically. This parameter is an array, but the current version processes only the first element. Valid values vary by model: - cosyvoice-v3-plus: zh: Chinese - en: English - fr: French - de: German - ja: Japanese - ko: Korean - ru: Russian - cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: zh: Chinese - en: English - fr: French - de: German - ja: Japanese - ko: Korean - ru: Russian - pt: Portuguese - th: Thai - id: Indonesian - vi: Vietnamese Default: ["zh"].
maxPromptAudioLength(Float)	Float	Important ** Applies only to CosyVoice voice cloning (when model is `voice-enrollment`). Supported only by cosyvoice-v3.5-plus, v3.5-flash, and v3-flash. The maximum duration (in seconds) of the reference audio after preprocessing. Valid values: [3.0, 30.0]. Longer durations produce better results. Default: 10.0.
parameter(String, Object)	Object	Sets Additional parameters , for example, parameter("enable_preprocess", false).

Additional parameters

Parameter	Type	Required	Description
enable_preprocess	boolean	No	Important ** Applies only to CosyVoice voice cloning (when model is `voice-enrollment`). Supported only by cosyvoice-v3.5-plus, v3.5-flash, and v3-flash. Whether to enable audio preprocessing (noise reduction, audio enhancement, and volume normalization). Enable this for recordings with background noise. Disable it for recordings in quiet environments to preserve the original voice characteristics. Default: false.

Sample code

Create a voice

HELPCODEESCAPE-java
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 org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.Collections;

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

    public static void main(String[] args) {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        String targetModel = "cosyvoice-v3-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)
                            .languageHints(Collections.singletonList("zh"))
                            // .maxPromptAudioLength(10.0f)
                            // .parameter("enable_preprocess", 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);
        }
    }
}

List voices

This example requires the third-party library com.google.gson.Gson.

HELPCODEESCAPE-java
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.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 {
        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));
    }
}

Retrieve a specific voice

This example requires the third-party library com.google.gson.Gson.

HELPCODEESCAPE-java
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.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 = "cosyvoice-v3-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 {
        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));
    }
}

Update a voice

HELPCODEESCAPE-java
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
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 = "cosyvoice-v3-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 {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Update the voice
        service.updateVoice(voiceId, fileUrl);
        logger.info("Update submitted. Request ID: {}", service.getLastRequestId());
    }
}

Delete a voice

HELPCODEESCAPE-java
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
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 = "cosyvoice-v3-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 {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Delete the voice
        service.deleteVoice(voiceId);
        logger.info("Deletion submitted. Request ID: {}", service.getLastRequestId());
    }
}

Voice cloning Java SDK reference ​

Service endpoint ​

International ​

Chinese mainland ​

VoiceEnrollmentService class ​

Constructor ​

createVoice() - Create a voice ​

listVoice() - List voices ​

queryVoice() - Retrieve voice details ​

updateVoice() - Update a voice ​

deleteVoice() - Delete a voice ​

VoiceEnrollmentParam class ​

Additional parameters ​

Sample code ​

Create a voice ​

List voices ​

Retrieve a specific voice ​

Update a voice ​

Delete a voice ​

Voice cloning Java SDK reference

Service endpoint

International

Chinese mainland

VoiceEnrollmentService class

Constructor

createVoice() - Create a voice

listVoice() - List voices

queryVoice() - Retrieve voice details

updateVoice() - Update a voice

deleteVoice() - Delete a voice

VoiceEnrollmentParam class

Additional parameters

Sample code

Create a voice

List voices

Retrieve a specific voice

Update a voice

Delete a voice