Java SDK - Qwen Cloud

CosyVoice voice cloning can be called via the DashScope Java SDK using the VoiceEnrollmentService class. This SDK covers voice cloning only — CosyVoice voice design and all Qwen voice cloning/design must use the HTTP API. User guide: Voice cloning.

Prerequisites

An API key
The latest DashScope SDK

Service URL

Set the base URL before creating the service:

import com.alibaba.dashscope.common.Constants;

Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

VoiceEnrollmentService class

Package: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService Manages the lifecycle of CosyVoice cloned voices (create, list, query, update, delete).

Constructor

public VoiceEnrollmentService(String apiKey)

Parameter	Type	Description
apiKey	String	Your DashScope API key.

createVoice()

Create a cloned voice from audio.

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

Parameter	Type	Required	Description
targetModel	String	Yes	Speech synthesis model for the cloned voice. Must match the model in your synthesis calls.
prefix	String	Yes	Voice name prefix. Alphanumeric only, max 10 characters.
url	String	Yes	Audio file URL for cloning. Must be publicly accessible.
customParam	VoiceEnrollmentParam	No	Optional parameters (languageHints, maxPromptAudioLength, etc.). See VoiceEnrollmentParam.

Returns: Voice object. Call getVoiceId() to get the voice ID.

Show Example

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.common.Constants;

Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";

String apiKey = System.getenv("DASHSCOPE_API_KEY");
VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);

Voice voice = service.createVoice(
  "cosyvoice-v3-plus",
  "myvoice",
  "https://your-audio-url.wav",
  null
);

System.out.println("Created voice: " + voice.getVoiceId());

listVoice()

List cloned voices with optional filtering and pagination.

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

Parameter	Type	Required	Description
prefix	String	No	Filter voices by name prefix.
pageIndex	int	No	Page number, starting from 0.
pageSize	int	No	Results per page.

Returns: Voice[] — array of voice objects.

Show Example

Voice[] voices = service.listVoice("myvoice", 0, 10);

for (Voice v : voices) {
  System.out.println("Voice: " + v.getVoiceId());
}

queryVoice()

Query details of a specific cloned voice.

public Voice queryVoice(String voiceId)
    throws NoApiKeyException, InputRequiredException

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

Returns: Voice object with status, target model, and other details.

Show Example

Voice details = service.queryVoice("cosyvoice-v3-plus-myvoice-xxxxxx");

System.out.println("Status: " + details.getStatus());

updateVoice()

Update a cloned voice with new audio.

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

Parameter	Type	Required	Description
voiceId	String	Yes	The voice ID to update.
url	String	Yes	New audio file URL. Must be publicly accessible.
customParam	VoiceEnrollmentParam	No	Optional parameters.

Show Example

service.updateVoice(
  "cosyvoice-v3-plus-myvoice-xxxxxx",
  "https://new-audio-url.wav",
  null
);

System.out.println("Voice updated successfully");

deleteVoice()

Delete a cloned voice.

public void deleteVoice(String voiceId)
    throws NoApiKeyException, InputRequiredException

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

Show Example

service.deleteVoice("cosyvoice-v3-plus-myvoice-xxxxxx");

System.out.println("Voice deleted successfully");

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.common.Constants;
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) {
    Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
    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.

import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.common.Constants;
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");
  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 {
    Constants.baseHttpApiUrl = "https://dashscope-intl.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));
  }
}

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.common.Constants;
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");
  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 {
    Constants.baseHttpApiUrl = "https://dashscope-intl.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));
  }
}

Update a voice

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.common.Constants;
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");
  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 {
    Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
    VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
    // Update the voice
    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.common.Constants;
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");
  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 {
    Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
    VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
    // Delete the voice
    service.deleteVoice(voiceId);
    logger.info("Deletion submitted. Request ID: {}", service.getLastRequestId());
  }
}

VoiceEnrollmentParam class

Package: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam Use the Builder pattern to construct optional parameters for createVoice() and updateVoice().

Builder method	Type	Description
languageHints(List<String>)	List<String>	Language hint for the audio. Only the first element is used. Default: `["zh"]`.
maxPromptAudioLength(Float)	Float	Max audio duration (seconds) after preprocessing. Range: [3.0, 30.0]. Default: 10.0.
parameter(String, Object)	Object	Set additional parameters, e.g. `parameter("enable_preprocess", false)`.

enable_preprocess

Parameter	Type	Required	Description
enable_preprocess	boolean	No	Enable audio preprocessing (noise reduction, enhancement, volume normalization). Recommended for noisy audio; disable for clean audio. Default: `false`.

Show Example with VoiceEnrollmentParam

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam;
import java.util.Arrays;

VoiceEnrollmentParam param = VoiceEnrollmentParam.builder()
  .languageHints(Arrays.asList("en"))
  .maxPromptAudioLength(20.0f)
  .parameter("enable_preprocess", true)
  .build();

Voice voice = service.createVoice(
  "cosyvoice-v3-plus",
  "myvoice",
  "https://your-audio-url.wav",
  param
);

​Prerequisites

​Service URL

​VoiceEnrollmentService class

​Constructor

​createVoice()

​listVoice()

​queryVoice()

​updateVoice()

​deleteVoice()

​Sample code

​Create a voice

​List voices

​Retrieve a specific voice

​Update a voice

​Delete a voice

​VoiceEnrollmentParam class

​enable_preprocess

Prerequisites

Service URL

VoiceEnrollmentService class

Constructor

createVoice()

listVoice()

queryVoice()

updateVoice()

deleteVoice()

Sample code

Create a voice

List voices

Retrieve a specific voice

Update a voice

Delete a voice

VoiceEnrollmentParam class

enable_preprocess