百炼平台声音复刻 - Python SDK 调用指南

概述

CosyVoice 声音复刻服务基于生成式语音大模型，使用 10~20 秒音频样本即可生成高度相似且自然的定制声音，无需传统训练过程。声音复刻与语音合成是前后关联的两个步骤。

重要提示： 本文档仅适用于"中国大陆（北京）"地域。如需使用模型，需使用"中国大陆（北京）"地域的 API Key。

音频要求

高质量的输入音频是获得优质复刻效果的基础。

项目	要求
支持格式	WAV (16bit), MP3, M4A
音频时长	推荐 10~20 秒，最长不得超过 60 秒
文件大小	≤ 10 MB
采样率	≥ 16 kHz
声道	单声道 / 双声道
内容	音频必须包含至少 5 秒连续清晰朗读（无背景音），其余部分仅允许短暂停顿（≤2 秒）；整段音频应避免背景音乐、噪音或其他人声，确保核心朗读内容质量；请使用正常说话音频作为输入，不要上传歌曲或唱歌音频，以确保复刻效果准确和可用。
语言	因驱动音色的语音合成模型（通过 `target_model` 参数指定）而异： - cosyvoice-v2：中文（普通话）、英文 - cosyvoice-v3-flash、cosyvoice-v3-plus：中文（普通话、广东话、东北话、甘肃话、贵州话、河南话、湖北话、江西话、闽南话、宁夏话、山西话、陕西话、山东话、上海话、四川话、天津话、云南话）、英文、法语、德语、日语、韩语、俄语

快速开始：从复刻到合成

1. 工作流程

声音复刻与语音合成是紧密关联的两个独立步骤，遵循"先创建，后使用"的流程：

步骤一：创建音色

调用创建音色接口，上传一段音频。系统会分析该音频，创建一个专属的复刻音色。此步骤必须指定 target_model，声明创建的音色将由哪个语音合成模型驱动。

若已有创建好的音色（调用查询音色列表接口查看），可跳过这一步直接进行下一步。

步骤二：使用音色进行语音合成

调用语音合成接口，传入上一步获得的音色。此步骤指定的语音合成模型必须和上一步的 target_model 一致。

2. 模型配置与准备工作

模型配置

声音复刻时需要指定以下两个模型：

声音复刻模型：voice-enrollment
驱动音色的语音合成模型：

在资源与预算允许的情况下，推荐使用 cosyvoice-v3-plus 以获得最佳效果。

版本	适用场景
cosyvoice-v3-plus	追求最佳音质与表现力，预算充足
cosyvoice-v3-flash	平衡效果与成本，综合性价比高
cosyvoice-v2	兼容旧版或低要求场景

准备工作

获取 API Key：获取与配置 API Key，为安全起见，推荐将 API Key 配置到环境变量
安装 SDK：确保已安装最新版 DashScope SDK：pip install -U dashscope
准备音频 URL：将符合音频要求的音频文件上传至公网可访问的位置，如阿里云对象存储 OSS，并确保 URL 可公开访问

3. 端到端示例：从复刻到合成

以下示例演示了如何在语音合成中使用声音复刻生成的专属音色，实现与原音高度相似的输出效果。

关键原则：声音复刻时，target_model（驱动音色的语音合成模型）必须与后续调用语音合成接口时指定的语音合成模型一致，否则会合成失败。

注意将示例中的 AUDIO_URL 替换为实际的音频 URL。

import os
import time
import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService, SpeechSynthesizer

# 1. 环境准备
# 推荐通过环境变量配置API Key
# export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
if not dashscope.api_key:
    raise ValueError("DASHSCOPE_API_KEY environment variable not set.")

# 2. 定义复刻参数
TARGET_MODEL = "cosyvoice-v3-plus"
# 为音色起一个有意义的前缀
VOICE_PREFIX = "myvoice"  # 仅允许数字和小写字母，小于十个字符
# 公网可访问音频URL
AUDIO_URL = "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/cosyvoice/cosyvoice-zeroshot-sample.wav"  # 示例URL，请替换为自己的

# 3. 创建音色 (异步任务)
print("--- Step 1: Creating voice enrollment ---")
service = VoiceEnrollmentService()
try:
    voice_id = service.create_voice(
        target_model=TARGET_MODEL,
        prefix=VOICE_PREFIX,
        url=AUDIO_URL
    )
    print(f"Voice enrollment submitted successfully. Request ID: {service.get_last_request_id()}")
    print(f"Generated Voice ID: {voice_id}")
except Exception as e:
    print(f"Error during voice creation: {e}")
    raise e

# 4. 轮询查询音色状态
print("\n--- Step 2: Polling for voice status ---")
max_attempts = 30
poll_interval = 10  # 秒

for attempt in range(max_attempts):
    try:
        voice_info = service.query_voice(voice_id=voice_id)
        status = voice_info.get("status")
        print(f"Attempt {attempt + 1}/{max_attempts}: Voice status is '{status}'")
        
        if status == "OK":
            print("Voice is ready for synthesis.")
            break
        elif status == "UNDEPLOYED":
            print(f"Voice processing failed with status: {status}. Please check audio quality or contact support.")
            raise RuntimeError(f"Voice processing failed with status: {status}")
        
        # 对于 "DEPLOYING" 等中间状态，继续等待
        time.sleep(poll_interval)
    except Exception as e:
        print(f"Error during status polling: {e}")
        time.sleep(poll_interval)
else:
    print("Polling timed out. The voice is not ready after several attempts.")
    raise RuntimeError("Polling timed out. The voice is not ready after several attempts.")

# 5. 使用复刻音色进行语音合成
print("\n--- Step 3: Synthesizing speech with the new voice ---")
try:
    synthesizer = SpeechSynthesizer(model=TARGET_MODEL, voice=voice_id)
    text_to_synthesize = "恭喜，已成功复刻并合成了属于自己的声音！"
    
    # call()方法返回二进制音频数据
    audio_data = synthesizer.call(text_to_synthesize)
    print(f"Speech synthesis successful. Request ID: {synthesizer.get_last_request_id()}")
    
    # 6. 保存音频文件
    output_file = "my_custom_voice_output.mp3"
    with open(output_file, "wb") as f:
        f.write(audio_data)
    print(f"Audio saved to {output_file}")
except Exception as e:
    print(f"Error during speech synthesis: {e}")

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 指定目标语言，帮助提升合成效果准确性，对英文、法语、德语、日语、韩语、俄语生效
                         （无需填写中文），当前仅支持选择一种，取值范围：en、fr、de、ja、ko、ru。
    return: voice_id 音色ID，可直接用于语音合成接口的voice参数。
    '''

重要提示：

target_model：驱动音色的语音合成模型，须和后续调用语音合成接口时使用的语音合成模型一致，否则合成会失败
language_hints：仅适用于 cosyvoice-v3-flash 和 cosyvoice-v3-plus 模型

请求示例

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=['en']
)

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

查询音色列表

分页查询已创建的音色列表。

接口说明

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"
    }
]

响应参数

参数	类型	说明
voice_id	string	音色ID
gmt_create	string	创建音色的时间
gmt_modified	string	修改音色的时间
status	string	音色状态： - DEPLOYING：审核中 - OK：审核通过，可调用 - UNDEPLOYED：审核不通过，不可调用

查询指定音色

获取特定音色的详细信息。

接口说明

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"
}

响应参数

参数	类型	说明
resource_link	string	被复刻的音频的URL
target_model	string	驱动音色的语音合成模型，推荐 cosyvoice-v3-flash 或 cosyvoice-v3-plus 必须与后续调用语音合成接口时使用的语音合成模型一致，否则合成会失败
gmt_create	string	创建音色的时间
gmt_modified	string	修改音色的时间
status	string	音色状态： - DEPLOYING：审核中 - OK：审核通过，可调用 - UNDEPLOYED：审核不通过，不可调用

更新音色

使用新的音频文件更新一个已存在的音色。

接口说明

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()}")

删除音色

删除一个不再需要的音色以释放配额。此操作不可逆。

接口说明

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()}")

音色配额与自动清理规则

总数限制：1000 个音色/账号
自动清理：若单个音色在过去一年内未被用于任何语音合成请求，系统将自动将其删除

计费说明

声音复刻：创建、查询、更新、删除音色免费
使用复刻生成的专属音色进行语音合成：按量（文本字符数）计费

版权与合法性

您需对所提供声音的所有权及合法使用权负责，请注意阅读服务协议。

常见问题

功能特性

Q：如何调节自定义音色的语速、音量？

与使用预置音色完全相同。在调用语音合成 API 时，传入相应的参数即可，例如 speech_rate 用于调节语速，volume 用于调节音量。详情请参见语音合成 API 文档。

Q：除了 Java 和 Python，其他语言（如 Go, C#, Node.js）如何调用？

对于音色管理，请直接使用文档中提供的 RESTful API。对于语音合成，请使用 WebSocket API，并将复刻得到的 voice_id 作为 voice 参数传入。

故障排查

Q：为什么找不到 VoiceEnrollmentService 类？

SDK 版本过低。请安装最新版 SDK：pip install -U dashscope

Q：声音复刻效果不佳，有杂音或不清晰怎么办？

这通常是由于输入音频质量不高导致的。请严格遵循录音操作指南重新录制并上传音频。

声音复刻.md 15 KB Постоянная ссылка История Исходник

百炼平台声音复刻 - Python SDK 调用指南

概述

音频要求

快速开始：从复刻到合成

1. 工作流程

2. 模型配置与准备工作

模型配置

准备工作

3. 端到端示例：从复刻到合成

API 参考

创建音色

接口说明

请求示例

查询音色列表

接口说明

请求示例

响应示例

响应参数

查询指定音色

接口说明

请求示例

响应示例

响应参数

更新音色

接口说明

请求示例

删除音色

接口说明

请求示例

音色配额与自动清理规则

计费说明

版权与合法性

常见问题

功能特性

Q：如何调节自定义音色的语速、音量？

Q：除了 Java 和 Python，其他语言（如 Go, C#, Node.js）如何调用？

故障排查

Q：为什么找不到 VoiceEnrollmentService 类？

Q：声音复刻效果不佳，有杂音或不清晰怎么办？

参考文档

声音复刻.md 15 KB

Постоянная ссылка История Исходник