Java SDK - 千问云

通过 DashScope Java SDK 的 VoiceEnrollmentService 类调用 CosyVoice 声音复刻。该 SDK 仅覆盖声音复刻功能，CosyVoice 声音设计以及所有 Qwen 声音复刻/设计请使用 HTTP API。 用户指南：声音复刻。

前提条件

Service URL

创建服务前设置 base URL：

import com.alibaba.dashscope.common.Constants;

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

VoiceEnrollmentService 类

包路径：com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService 管理 CosyVoice 克隆音色的完整生命周期（创建、列表、查询、更新、删除）。

构造方法

public VoiceEnrollmentService(String apiKey)

参数	类型	说明
apiKey	String	DashScope API Key。

createVoice()

从音频创建克隆音色。

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

参数	类型	必选	说明
targetModel	String	是	克隆音色绑定的语音合成模型。后续合成调用的 model 必须与此一致。
prefix	String	是	音色名称前缀，仅限字母和数字，最长 10 个字符。
url	String	是	用于克隆的音频文件 URL，必须可公开访问。
customParam	VoiceEnrollmentParam	否	可选参数（languageHints、maxPromptAudioLength 等），详见 VoiceEnrollmentParam。

返回值：Voice 对象，调用 getVoiceId() 获取音色 ID。

显示示例

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.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()

列出克隆音色，支持前缀过滤和分页。

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

参数	类型	必选	说明
prefix	String	否	按名称前缀过滤。
pageIndex	int	否	页码，从 0 开始。
pageSize	int	否	每页条数。

返回值：Voice[] 音色对象数组。

显示示例

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

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

queryVoice()

查询指定克隆音色的详细信息。

public Voice queryVoice(String voiceId)
    throws NoApiKeyException, InputRequiredException

参数	类型	必选	说明
voiceId	String	是	要查询的音色 ID。

返回值：Voice 对象，包含状态、目标模型等信息。

显示示例

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

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

updateVoice()

用新音频更新已有克隆音色。

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

参数	类型	必选	说明
voiceId	String	是	要更新的音色 ID。
url	String	是	新的音频文件 URL，必须可公开访问。
customParam	VoiceEnrollmentParam	否	可选参数。

显示示例

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

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

deleteVoice()

删除克隆音色。

public void deleteVoice(String voiceId)
    throws NoApiKeyException, InputRequiredException

参数	类型	必选	说明
voiceId	String	是	要删除的音色 ID。

显示示例

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

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

完整示例

创建音色

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

列表查询

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";
  private static final Logger logger = LoggerFactory.getLogger(Main.class);

  public static void main(String[] args)
      throws NoApiKeyException, InputRequiredException {
    Constants.baseHttpApiUrl = "https://dashscope.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));
  }
}

查询音色详情

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";
  private static final Logger logger = LoggerFactory.getLogger(Main.class);

  public static void main(String[] args)
      throws NoApiKeyException, InputRequiredException {
    Constants.baseHttpApiUrl = "https://dashscope.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));
  }
}

更新音色

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";
  private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx";
  private static final Logger logger = LoggerFactory.getLogger(Main.class);

  public static void main(String[] args)
      throws NoApiKeyException, InputRequiredException {
    Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
    VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
    service.updateVoice(voiceId, fileUrl);
    logger.info("Update submitted. Request ID: {}", service.getLastRequestId());
  }
}

删除音色

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";
  private static final Logger logger = LoggerFactory.getLogger(Main.class);

  public static void main(String[] args)
      throws NoApiKeyException, InputRequiredException {
    Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
    VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
    service.deleteVoice(voiceId);
    logger.info("Deletion submitted. Request ID: {}", service.getLastRequestId());
  }
}

VoiceEnrollmentParam 类

包路径：com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam 使用 Builder 模式构造 createVoice() 和 updateVoice() 的可选参数。

Builder 方法	类型	说明
model(String)	String	声音复刻模型，固定为 `voice-enrollment`。
languageHints(List<String>)	List<String>	音频的语言提示，仅使用第一个元素。默认：`["zh"]`。
maxPromptAudioLength(Float)	Float	预处理后的最大音频时长（秒）。范围：[3.0, 30.0]。默认：10.0。
parameter(String, Object)	Object	设置额外参数，如 `parameter("enable_preprocess", false)`。

enable_preprocess

参数	类型	必选	说明
enable_preprocess	boolean	否	是否启用音频预处理（降噪、增强、音量归一化）。有噪音的音频建议开启，干净音频建议关闭。默认：`false`。

显示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
);

​前提条件

​Service URL

​VoiceEnrollmentService 类

​构造方法

​createVoice()

​listVoice()

​queryVoice()

​updateVoice()

​deleteVoice()

​完整示例

​创建音色

​列表查询

​查询音色详情

​更新音色

​删除音色

​VoiceEnrollmentParam 类

​enable_preprocess

前提条件

Service URL

VoiceEnrollmentService 类

构造方法

createVoice()

listVoice()

queryVoice()

updateVoice()

deleteVoice()

完整示例

创建音色

列表查询

查询音色详情

更新音色

删除音色

VoiceEnrollmentParam 类

enable_preprocess