Alibaba Cloud Model Studio：CosyVoice聲音複刻API

介面說明

def create_voice(self, target_model: str, prefix: str, url: str, language_hints: List[str] = None) -> str:
    '''
    建立一個新的定製音色。
    param: target_model 驅動音色的語音合成模型，必須與後續調用語音合成介面時使用的語音合成模型一致，否則合成會失敗。推薦 cosyvoice-v3-flash 或 cosyvoice-v3-plus。
    param: prefix 為音色指定一個便於識別的名稱（僅允許數字、大小寫字母和底線，不超過10個字元）。建議選用與角色、情境相關的標識。該關鍵字會在複刻的音色名中出現，產生的音色名格式為：模型名-首碼-唯一標識，如cosyvoice-v3-plus-myvoice-xxxxxxxx。
    param: url 用於複刻音色的音頻檔案URL，要求公網可訪問。
    param: language_hints 指定用於提取目標音色特徵的樣本音頻語種，僅適用於 cosyvoice-v3-flash 和 cosyvoice-v3-plus 模型。
            該參數用於輔助模型識別樣本音頻（原始參考音頻）的語種，從而更準確地提取音色特徵，提升複刻效果。
            若設定的語言提示與實際音頻語言不符（例如為中文音頻設定 en），系統將忽略此提示，並依據音頻內容自動檢測語言。
            取值範圍：zh（預設值）、en、fr、de、ja、ko、ru。此參數為數組，但目前的版本僅處理第一個元素，建議只傳入一個值。
    return: voice_id 音色ID，可直接用於語音合成介面的voice參數。
    '''

請求樣本

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()

# 避免頻繁調用。每次調用都會建立新音色，達到配額上限後將無法建立。
voice_id = service.create_voice(
    target_model='cosyvoice-v3-plus',
    prefix='myvoice',
    url='https://your-audio-file-url',
    language_hints=['zh']
)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Voice ID: {voice_id}")

介面說明

/**
 * 建立一個新的定製音色。
 *
 * @param targetModel 驅動音色的語音合成模型，必須與後續調用語音合成介面時使用的語音合成模型一致，否則合成會失敗。推薦 cosyvoice-v3-flash 或 cosyvoice-v3-plus。
 * @param prefix 為音色指定一個便於識別的名稱（僅允許數字、大小寫字母和底線，不超過10個字元）。建議選用與角色、情境相關的標識。該關鍵字會在複刻的音色名中出現，產生的音色名格式為：模型名-首碼-唯一標識，如cosyvoice-v3-plus-myvoice-xxxxxxxx。
 * @param url 用於複刻音色的音頻檔案URL，要求公網可訪問。
 * @param customParam 自訂參數。可在此處指定languageHints。
 *                  languageHints指定用於提取目標音色特徵的樣本音頻語種，僅適用於 cosyvoice-v3-flash 和 cosyvoice-v3-plus 模型。
 *                  該參數用於輔助模型識別樣本音頻（原始參考音頻）的語種，從而更準確地提取音色特徵，提升複刻效果。
 *                  若設定的語言提示與實際音頻語言不符（例如為中文音頻設定 en），系統將忽略此提示，並依據音頻內容自動檢測語言。
 *                  取值範圍：zh（預設值）、en、fr、de、ja、ko、ru。此參數為數組，但目前的版本僅處理第一個元素，建議只傳入一個值。
 * @return Voice 新建立的音色，通過Voice的getVoiceId方法能夠擷取音色ID，可直接用於語音合成介面的voice參數。
 * @throws NoApiKeyException 如果apikey為空白。
 * @throws InputRequiredException 如果必須參數為空白。
 */
public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException

請求樣本

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 org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.Collections;

public class Main {
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args) {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        String targetModel = "cosyvoice-v3-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)
                    .languageHints(Collections.singletonList("zh")).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);
        }
    }
}

介面說明

def list_voices(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
    '''
    查詢已建立的所有音色
    param: prefix 音色自訂首碼，僅允許數字和小寫字母，長度小於10個字元。
    param: page_index 查詢的頁索引
    param: page_size 查詢頁大小
    return: List[dict] 音色列表，包含每個音色的id，建立時間，修改時間，狀態。格式為：[{'gmt_create': '2025-10-09 14:51:01', 'gmt_modified': '2025-10-09 14:51:07', 'status': 'OK', 'voice_id': 'cosyvoice-v3-myvoice-xxx'}]
    音色狀態有三種：
        DEPLOYING： 審核中
        OK：審核通過，可調用
        UNDEPLOYED：審核不通過，不可調用
    '''

請求樣本

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()

# 按首碼篩選，或設為None查詢所有
voices = service.list_voices(prefix='myvoice', page_index=0, page_size=10)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Found voices: {voices}")

響應樣本

[
    {
        "gmt_create": "2024-09-13 11:29:41",
        "voice_id": "yourVoiceId",
        "gmt_modified": "2024-09-13 11:29:41",
        "status": "OK"
    },
    {
        "gmt_create": "2024-09-13 13:22:38",
        "voice_id": "yourVoiceId",
        "gmt_modified": "2024-09-13 13:22:38",
        "status": "OK"
    }
]

響應參數

介面說明

// 音色狀態有三種：
//        DEPLOYING： 審核中
//        OK：審核通過，可調用
//        UNDEPLOYED：審核不通過，不可調用
/**
 * 查詢已建立的所有音色 預設的頁索引為0，預設的頁大小為10
 *
 * @param prefix 音色自訂首碼，僅允許數字和小寫字母，長度小於10個字元。可以為null。
 * @return Voice[] 音色對象數組。Voice封裝了音色的id，建立時間，修改時間，狀態。
 * @throws NoApiKeyException 如果apikey為空白。
 * @throws InputRequiredException 如果必須參數為空白。
 */
public Voice[] listVoice(String prefix) throws NoApiKeyException, InputRequiredException 

/**
 * 查詢已建立的所有音色
 *
 * @param prefix 音色自訂首碼，僅允許數字和小寫字母，長度小於10個字元。
 * @param pageIndex 查詢的頁索引。
 * @param pageSize 查詢的頁大小。
 * @return Voice[] 音色對象數組。Voice封裝了音色的id，建立時間，修改時間，狀態。
 * @throws NoApiKeyException 如果apikey為空白。
 * @throws InputRequiredException 如果必須參數為空白。
 */
public Voice[] listVoice(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException

請求樣本

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

響應樣本

[
    {
        "gmt_create": "2024-09-13 11:29:41",
        "voice_id": "yourVoiceId",
        "gmt_modified": "2024-09-13 11:29:41",
        "status": "OK"
    },
    {
        "gmt_create": "2024-09-13 13:22:38",
        "voice_id": "yourVoiceId",
        "gmt_modified": "2024-09-13 13:22:38",
        "status": "OK"
    }
]

響應參數

介面說明

def query_voice(self, voice_id: str) -> List[str]:
    '''
    查詢指定音色的詳細資料
    param: voice_id 需要查詢的音色ID
    return: List[str] 音色詳細資料，包含狀態、建立時間、音頻連結等
    '''

請求樣本

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()
voice_id = 'cosyvoice-v3-plus-myvoice-xxxxxxxx'

voice_details = service.query_voice(voice_id=voice_id)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Voice Details: {voice_details}")

響應樣本

{
    "gmt_create": "2024-09-13 11:29:41",
    "resource_link": "https://yourAudioFileUrl",
    "target_model": "cosyvoice-v3-plus",
    "gmt_modified": "2024-09-13 11:29:41",
    "status": "OK"
}

響應參數

介面說明

/**
 * 查詢指定音色的詳細資料
 *
 * @param voiceId 需要查詢的音色ID
 * @return Voice 音色詳細資料，包含狀態、建立時間、音頻連結等
 * @throws NoApiKeyException 如果apikey為空白
 * @throws InputRequiredException 如果必須參數為空白
 */
public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

請求樣本

需要引入第三方庫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.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 = "cosyvoice-v3-plus-myvoice-xxx"; // 請按實際情況進行替換
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        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));
    }
}

響應樣本

{
    "gmt_create": "2024-09-13 11:29:41",
    "resource_link": "https://yourAudioFileUrl",
    "target_model": "cosyvoice-v3-plus",
    "gmt_modified": "2024-09-13 11:29:41",
    "status": "OK"
}

響應參數

介面說明

def update_voice(self, voice_id: str, url: str) -> None:
    '''
    更新音色
    param: voice_id 音色id
    param: url 用於聲音複刻的音頻檔案url
    '''

請求樣本

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()
service.update_voice(
    voice_id='cosyvoice-v3-plus-myvoice-xxxxxxxx',
    url='https://your-new-audio-file-url'
)
print(f"Update submitted. Request ID: {service.get_last_request_id()}")

介面說明

/**
 * 更新音色
 *
 * @param voiceId 需要更新的音色
 * @param url 用於聲音複刻的音頻檔案url
 * @throws NoApiKeyException 如果apikey為空白
 * @throws InputRequiredException 如果必須參數為空白
 */
public void updateVoice(String voiceId, String url)
    throws NoApiKeyException, InputRequiredException

請求樣本

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
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 = "cosyvoice-v3-plus-myvoice-xxx"; // 請按實際情況進行替換
    private static final Logger logger = LoggerFactory.getLogger(Main.class);
    
    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // 更新音色
        service.updateVoice(voiceId, fileUrl);
        logger.info("Update submitted. Request ID: {}", service.getLastRequestId());
    }
}

介面說明

def delete_voice(self, voice_id: str) -> None:
    '''
    刪除音色
    param: voice_id 需要刪除的音色
    '''

請求樣本

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()
service.delete_voice(voice_id='cosyvoice-v3-plus-myvoice-xxxxxxxx')
print(f"Deletion submitted. Request ID: {service.get_last_request_id()}")

介面說明

/**
 * 刪除音色
 *
 * @param voiceId 需要刪除的音色
 * @throws NoApiKeyException 如果apikey為空白
 * @throws InputRequiredException 如果必須參數為空白
 */
public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException 

請求樣本

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
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 = "cosyvoice-v3-plus-myvoice-xxx"; // 請按實際情況進行替換
    private static final Logger logger = LoggerFactory.getLogger(Main.class);
    
    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // 刪除音色
        service.deleteVoice(voiceId);
        logger.info("Deletion submitted. Request ID: {}", service.getLastRequestId());
    }
}