Qwen-Audio and CosyVoice voice cloning Java SDK reference
Clone and manage Qwen-Audio and CosyVoice voices with the DashScope Java SDK.
Service endpoint
The SDK endpoint must be set to the address below (which includes the WorkspaceId) before initialization. To switch to a different region, modify Constants.baseHttpApiUrl to the URL of that region.
Note
- API keys differ by region. Use the API key for the target region.
- The region setting is global and affects all DashScope SDK API calls.
China (Beijing)
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
Replace {WorkspaceId} with your actual workspace ID.
Singapore
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
Replace {WorkspaceId} with your actual workspace ID.
ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
- China (Beijing): from
dashscope.aliyuncs.comto{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
dashscope-intl.aliyuncs.comto{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
VoiceEnrollmentService class
Package: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService
Purpose: Manage the lifecycle of Qwen-Audio-TTS, Qwen-Audio-Realtime, and CosyVoice cloned voices (create, query, update, and delete).
Constructor
public VoiceEnrollmentService(String apiKey)
Parameters:
| Parameter | Type | Description |
|---|---|---|
apiKey | String | API key |
createVoice() - Create a voice
Method signature:
public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
targetModel | String | Yes | The target model that uses the voice. It must match the model used in subsequent requests with this voice; otherwise, the requests fail. |
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: |
url | String | Yes | Reference audio for voice cloning. Accepts a publicly accessible URL or a Base64 Data URI, such as |
customParam | No | Custom parameters. You can use the parameter() method to specify parameters such as language_hints and max_prompt_audio_length. |
Return value: A Voice object. Call getVoiceId() to retrieve the voice ID.
listVoice() - List voices
Method signature:
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. If getTargetModel() returns null for a list item, read the target model ID from voice.getData().get("target_model").
queryVoice() - Retrieve voice details
Method signature:
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. Use getTargetModel() to get the target model ID.
updateVoice() - Update a voice
Method signature:
public void updateVoice(String voiceId, String url) throws NoApiKeyException, InputRequiredException
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 | New reference audio. Accepts a publicly accessible URL or a Base64 Data URI, such as |
customParam | VoiceEnrollmentParam | No | Custom parameters. |
deleteVoice() - Delete a voice
Method signature:
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". |
parameter(String, Object) | Object | Sets custom parameters, such as parameter("language_hints", Arrays.asList("zh")), parameter("max_prompt_audio_length", 10.0f), parameter("enable_preprocess", false), and parameter("enable_volume_normalization", "false"). NoteThe |
Additional parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
enable_preprocess | boolean | No | 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. NoteApplies to 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.1-realtime-flash, 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 | Whether to normalize the volume of the sample audio used for voice cloning. Valid values are |
Sample code
Create a voice
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) {
// 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.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("zh"))
// .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);
}
}
}
For a local WAV file, add the following assignment inside the try block above, before calling createVoice. To update a voice, also pass the Data URI through the url parameter of updateVoice. Replace sample.wav with your local audio path.
fileUrl = "data:audio/wav;base64," + java.util.Base64.getEncoder().encodeToString(
java.nio.file.Files.readAllBytes(java.nio.file.Paths.get("sample.wav")));
List voices
This example requires the third-party library 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"); // 如果您没有配置环境变量,请在此处用您的API-KEY进行替换
private static String prefix = "myvoice"; // 请按实际情况进行替换
private static final Logger logger = LoggerFactory.getLogger(Main.class);
public static void main(String[] args)
throws NoApiKeyException, InputRequiredException {
// 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
// 查询音色
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("Target model: {}", voice.getData().get("target_model"));
}
}
}
Retrieve a specific voice
This example requires the third-party library 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"); // 如果您没有配置环境变量,请在此处用您的API-KEY进行替换
private static String voiceId = "qwen-audio-3.1-tts-plus-myvoice-xxx"; // 请按实际情况进行替换
private static final Logger logger = LoggerFactory.getLogger(Main.class);
public static void main(String[] args)
throws NoApiKeyException, InputRequiredException {
// 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.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("Target model: {}", voice.getTargetModel());
}
}
Update a 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 org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class Main {
public static String apiKey = System.getenv("DASHSCOPE_API_KEY"); // 如果您没有配置环境变量,请在此处用您的API-KEY进行替换
private static String fileUrl = "https://your-audio-file-url"; // 请按实际情况进行替换
private static String voiceId = "qwen-audio-3.1-tts-plus-myvoice-xxx"; // 请按实际情况进行替换
private static final Logger logger = LoggerFactory.getLogger(Main.class);
public static void main(String[] args)
throws NoApiKeyException, InputRequiredException {
// 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
// 更新音色
service.updateVoice(voiceId, fileUrl);
logger.info("Update submitted. Request ID: {}", service.getLastRequestId());
}
}
Delete a 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 org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class Main {
public static String apiKey = System.getenv("DASHSCOPE_API_KEY"); // 如果您没有配置环境变量,请在此处用您的API-KEY进行替换
private static String voiceId = "qwen-audio-3.1-tts-plus-myvoice-xxx"; // 请按实际情况进行替换
private static final Logger logger = LoggerFactory.getLogger(Main.class);
public static void main(String[] args)
throws NoApiKeyException, InputRequiredException {
// 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
// 删除音色
service.deleteVoice(voiceId);
logger.info("Deletion submitted. Request ID: {}", service.getLastRequestId());
}
}