Skip to main content

聲音複刻Java SDK參考

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

介面地址

SDK的介面地址需在初始化前設定為下方地址（包含WorkspaceId）。如需切換到其他地區，請修改 Constants.baseHttpApiUrl為對應地區的URL。
  • 不同地區的 API Key 不同，呼叫時需使用對應地區的 API Key。
  • 地區設定為全域設定，影響所有 DashScope SDK API 呼叫。
  • 新加坡
  • 華北2（北京）
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1調用時請將{WorkspaceId}替換為真實的Workspace ID。
阿里雲百鍊為華北2（北京）、新加坡地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議遷移至新網域名稱：
  • 華北2（北京）地區：從 dashscope.aliyuncs.com 遷移至 {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區：從 dashscope-intl.aliyuncs.com 遷移至 {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

VoiceEnrollmentService 類

包路徑：com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService 功能：管理 Qwen-Audio-TTS、Qwen-Audio-Realtime 和 CosyVoice 複製音色的生命週期（建立、查詢、更新、刪除）。

構造方法 

public VoiceEnrollmentService(String apiKey)
參數說明：
參數類型說明
apiKeyStringAPI Key

createVoice() - 建立音色

方法簽名： 
public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException
參數說明：
參數類型必填說明
targetModelString是驅動音色的目標模型。必須與後續使用該音色的模型一致，否則呼叫失敗。
prefixString是音色名稱首碼，僅允許數字和英文字母，不超過10個字元。產生的音色名格式：{target_model}-{prefix}-{唯一標識}。
urlString是用於複刻音色的參考音訊，支援可公開存取的 URL 或 Base64 Data URI，例如 data:audio/wav;base64,...。
customParamVoiceEnrollmentParam否自訂參數，可通過 parameter() 方法指定 language_hints、max_prompt_audio_length 等參數。
傳回值：Voice 對象，通過 getVoiceId() 方法擷取音色ID。

listVoice() - 查詢音色列表

方法簽名： 
public Voice[] listVoice(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException
參數說明：
參數類型必填說明
prefixString否按音色名稱首碼篩選。
pageIndexint否頁碼索引，從0開始。
pageSizeint否每頁資料條數。
傳回值：Voice[] 音色數組。

queryVoice() - 查詢音色詳情

方法簽名： 
public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException
參數說明：
參數類型必填說明
voiceIdString是要查詢的音色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
參數說明：
參數類型必填說明
voiceIdString是要更新的音色ID。
urlString是新的參考音訊，支援可公開存取的 URL 或 Base64 Data URI，例如 data:audio/wav;base64,...。
customParamVoiceEnrollmentParam否自訂參數。

deleteVoice() - 刪除音色

方法簽名： 
public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException
參數說明：
參數類型必填說明
voiceIdString是要刪除的音色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_preprocessboolean否是否開啟音頻預先處理（降噪、音頻增強、音量規整）。有背景雜音時建議開啟；安靜環境建議關閉以最大程度還原音色。預設值：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_normalizationString否是否對用於聲音複刻的樣本音頻進行音量歸一化。取值為"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);
        }
    }
}
使用本機 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 {
        // 以下為華北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());
    }
}