透過 DashScope Java SDK 建立、查詢、更新和刪除 Qwen-Audio、CosyVoice 複刻音色。
介面地址
SDK的介面地址需在初始化前設定為下方地址(包含WorkspaceId)。如需切換到其他地區,請修改 Constants.baseHttpApiUrl為對應地區的URL。
說明
- 不同地區的 API Key 不同,呼叫時需使用對應地區的 API Key。
- 地區設定為全域設定,影響所有 DashScope SDK API 呼叫。
新加坡
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。
重要阿里雲百鍊為華北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)
參數說明:
| 參數 | 類型 | 說明 |
|---|---|---|
apiKey | String | API Key |
createVoice() - 建立音色
方法簽名:
public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException
參數說明:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
targetModel | String | 是 | 驅動音色的目標模型。必須與後續使用該音色的模型一致,否則呼叫失敗。 |
prefix | String | 是 | 音色名稱首碼,僅允許數字和英文字母,不超過10個字元。產生的音色名格式: |
url | String | 是 | 用於複刻音色的參考音訊,支援可公開存取的 URL 或 Base64 Data URI,例如 |
customParam | 否 | 自訂參數,可通過 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[] 音色數組。如果列表項目的 getTargetModel() 傳回 null,可透過 voice.getData().get("target_model") 讀取目標模型 ID。
queryVoice() - 查詢音色詳情
方法簽名:
public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException
參數說明:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
voiceId | String | 是 | 要查詢的音色ID。 |
傳回值:Voice 對象。透過 getTargetModel() 取得目標模型 ID。
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,例如 |
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 | 否 | 是否開啟音頻預先處理(降噪、音頻增強、音量規整)。有背景雜音時建議開啟;安靜環境建議關閉以最大程度還原音色。 預設值: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 | 否 | 是否對用於聲音複刻的樣本音頻進行音量歸一化。取值為 |
範例程式碼
建立音色
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.1-tts-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)
.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));
for (Voice voice : voices) {
logger.info("Target model: {}", voice.getData().get("target_model"));
}
}
}
查詢特定音色
需要引入第三方庫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.1-tts-plus-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));
logger.info("Target model: {}", voice.getTargetModel());
}
}
更新音色
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.1-tts-plus-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.1-tts-plus-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());
}
}