Voice cloning Java SDK reference - DashScope_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

本文介紹聲音複刻的Java SDK使用方法。

使用者指南：聲音複刻。

介面地址

SDK的介面地址需在初始化前設定為下方地址（包含WorkspaceId）。如需切換到其他地區，請修改 Constants.baseHttpApiUrl為對應地區的URL。

新加坡

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

調用時請將{WorkspaceId}替換為真實的Workspace ID。

華北2（北京）

https://{WorkspaceId}.cn-beijing.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());
    }
}