声音复刻Java SDK参考

用户指南：声音复刻。

接口地址

SDK 的接口地址需在初始化前设置为下方地址。 https://maas.qianwenaiapi.com/api/v1

VoiceEnrollmentService 类

包路径：com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService 功能：管理 Qwen-Audio-TTS、Qwen-Audio-Realtime 和 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 或 Base64 Data URI，例如 `data:audio/wav;base64,...`。
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 或 Base64 Data URI，例如 `data:audio/wav;base64,...`。
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")。 `language_hints` 数组的长度必须为 1。可选参数及其支持模型请参见HTTP API 参考。

扩展参数

参数名	类型	必填	说明
enable_preprocess	boolean	否	是否开启音频预处理（降噪、音频增强、音量规整）。有背景噪音时建议开启；安静环境建议关闭以最大程度还原音色。默认值：false。适用于 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.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash。
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) {
        Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.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);
        }
    }
}

使用本地 WAV 音频时，在上述 try 代码块内、调用 createVoice 前添加以下赋值。更新音色时，也通过 updateVoice 的 url 参数传入 Data URI。将 sample.wav 替换为本地音频路径。

fileUrl = "data:audio/wav;base64," + java.util.Base64.getEncoder().encodeToString(
        java.nio.file.Files.readAllBytes(java.nio.file.Paths.get("sample.wav")));

查询音色列表

需要引入第三方库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 {
        Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.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 {
        Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.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 {
        Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.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 {
        Constants.baseHttpApiUrl = "https://maas.qianwenaiapi.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // 删除音色
        service.deleteVoice(voiceId);
        logger.info("Deletion submitted. Request ID: {}", service.getLastRequestId());
    }
}

​接口地址

​VoiceEnrollmentService 类

​构造方法

​createVoice() - 创建音色

​listVoice() - 查询音色列表

​queryVoice() - 查询音色详情

​updateVoice() - 更新音色

​deleteVoice() - 删除音色

​VoiceEnrollmentParam 类

​扩展参数

​示例代码

​创建音色

​查询音色列表

​查询特定音色

​更新音色

​删除音色

接口地址

VoiceEnrollmentService 类

构造方法

createVoice() - 创建音色

listVoice() - 查询音色列表

queryVoice() - 查询音色详情

updateVoice() - 更新音色

deleteVoice() - 删除音色

VoiceEnrollmentParam 类

扩展参数

示例代码

创建音色

查询音色列表

查询特定音色

更新音色

删除音色