大模型服务平台百炼：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());
    }
}