声音复刻Java SDK参考-大模型服务平台百炼(Model Studio)-阿里云帮助中心

本文介绍声音复刻的Java SDK使用方法。

用户指南：声音复刻。

接口地址

SDK的接口地址需在初始化前设置为下方地址（包含WorkspaceId）。如需切换到其他地域，请修改 Constants.baseHttpApiUrl为对应地域的URL。

华北2（北京）

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

调用时请将{WorkspaceId}替换为真实的Workspace ID。

新加坡

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

调用时请将{WorkspaceId}替换为真实的Workspace ID。

切换到新加坡地域：

import com.alibaba.dashscope.utils.Constants;

// 调用时请将"{WorkspaceId}"替换为真实的业务空间ID
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

注意：

不同地域的 API Key 不同，请确保使用对应地域的 API Key
地域配置为全局设置，影响所有 DashScope SDK 的 API 调用

重要

阿里云百炼为华北2（北京）、新加坡地域推出了业务空间专属域名，能够为推理请求提供卓越的性能和更高的稳定性，建议迁移至新域名：

华北2（北京）地域：从 dashscope.aliyuncs.com 迁移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
新加坡地域：从 dashscope-intl.aliyuncs.com 迁移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId}需要替换为真实的Workspace ID。现有域名仍可正常使用。

VoiceEnrollmentService 类

包路径：com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService

功能：管理Qwen-Audio-TTS/CosyVoice复刻音色的生命周期（创建、查询、更新、删除）

构造方法

public VoiceEnrollmentService(String apiKey)

参数说明：

参数	类型	说明
apiKey	String	API Key

createVoice() - 创建音色

方法签名：

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

参数说明：

参数	类型	必填	说明
targetModel	String	是	驱动音色的语音合成模型。必须与后续调用语音合成接口时使用的模型一致，否则合成会失败。
prefix	String	是	音色名称前缀，仅允许数字和英文字母，不超过10个字符。生成的音色名格式：`{target_model}-{prefix}-{唯一标识}`。
url	String	是	用于复刻音色的音频文件URL，要求公网可访问。
customParam	VoiceEnrollmentParam	否	自定义参数，可通过 parameter() 方法指定 language_hints、max_prompt_audio_length 等参数。

返回值：Voice 对象，通过 getVoiceId() 方法获取音色ID。

listVoice() - 查询音色列表

方法签名：

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

参数说明：

参数	类型	必填	说明
prefix	String	否	按音色名称前缀筛选。
pageIndex	int	否	页码索引，从0开始。
pageSize	int	否	每页数据条数。

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

queryVoice() - 查询音色详情

方法签名：

public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

参数说明：

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

返回值：Voice 对象。

updateVoice() - 更新音色

方法签名：

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

参数说明：

参数	类型	必填	说明
voiceId	String	是	要更新的音色ID。
url	String	是	新的音频文件URL。
customParam	VoiceEnrollmentParam	否	自定义参数。

deleteVoice() - 删除音色

方法签名：

public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException

参数说明：

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

VoiceEnrollmentParam 类

包路径：com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam

通过Builder模式构建参数对象。

方法	类型	说明
model(String)	String	声音复刻模型，固定为"voice-enrollment"。
parameter(String, Object)	Object	设置自定义参数，如 parameter("language_hints", Arrays.asList("zh"))、parameter("max_prompt_audio_length", 10.0f)、parameter("enable_preprocess", false)、parameter("enable_volume_normalization", "false")。

扩展参数

参数名	类型	必填	说明
enable_preprocess	boolean	否	重要仅适用于Qwen-Audio-TTS/CosyVoice声音复刻（model为`voice-enrollment`时），且仅qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、cosyvoice-v3.5-plus、v3.5-flash和v3-flash模型支持。是否开启音频预处理（降噪、音频增强、音量规整）。有背景噪音时建议开启；安静环境建议关闭以最大程度还原音色。默认值：false。
enable_volume_normalization	String	否	是否对用于声音复刻的样本音频进行音量归一化。取值为`"true"`或`"false"`。开启后，使用所创建音色合成的音频，其音量可能与关闭该参数时创建的音色不同。默认值：`"false"`。

示例代码

创建音色

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

查询音色列表

需要引入第三方库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));
    }
}

查询特定音色

需要引入第三方库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.0-tts-flash-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));
    }
}

更新音色

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.0-tts-flash-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());
    }
}

删除音色

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.0-tts-flash-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());
    }
}