跳转到主要内容
千问 AI 平台 home page
文档
声音复刻

Python SDK

CosyVoice 声音复刻 Python SDK 参考（VoiceEnrollmentService）。

通过 DashScope Python SDK 的 VoiceEnrollmentService 类调用 CosyVoice 声音复刻。该 SDK 仅覆盖声音复刻功能，CosyVoice 声音设计以及所有 Qwen 声音复刻/设计请使用 HTTP API。 用户指南：声音复刻。

前提条件

Service URL

创建服务前设置 base URL： 
import dashscope

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

VoiceEnrollmentService 类

包路径：dashscope.audio.tts_v2.VoiceEnrollmentService 管理 CosyVoice 克隆音色的完整生命周期（创建、列表、查询、更新、删除）。

构造方法

VoiceEnrollmentService()

create_voice()

从音频创建克隆音色。 
def create_voice(self, target_model: str, prefix: str, url: str,
                 language_hints: List[str] = None,
                 max_prompt_audio_length: float = None,
                 enable_preprocess: bool = None) -> str
参数类型必选说明
target_modelstr是克隆音色绑定的语音合成模型。后续合成调用的 model 必须与此一致。
prefixstr是音色名称前缀，仅限字母和数字，最长 10 个字符。生成的名称格式：{target_model}-{prefix}-{unique_id}。
urlstr是用于克隆的音频文件 URL，必须可公开访问。
language_hintsList[str]否音频的语言提示，仅使用第一个元素。默认：["zh"]。qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash 支持的语言：zh（中文）、en（英文）、fr（法语）、de（德语）、ja（日语）、ko（韩语）、ru（俄语）、pt（葡萄牙语）、th（泰语）、id（印尼语）、vi（越南语）、it（意大利语）、es（西班牙语）、ms（马来语）、fil（菲律宾语）、ar（阿拉伯语）。
max_prompt_audio_lengthfloat否预处理后的最大音频时长（秒）。范围：[3.0, 30.0]。默认：10.0。
enable_preprocessbool否是否启用音频预处理（降噪、增强）。默认：False。
返回值：str，生成的音色 ID（voice_id）。

list_voice()

列出克隆音色，支持前缀过滤和分页。 
def list_voice(self, prefix: str = None, page_index: int = 0, page_size: int = 10) -> list
参数类型必选说明
prefixstr否按名称前缀过滤。
page_indexint否页码，从 0 开始。默认：0。
page_sizeint否每页条数。默认：10。
返回值：list，音色对象列表。

query_voice()

查询指定克隆音色的详细信息。 
def query_voice(self, voice_id: str) -> dict
参数类型必选说明
voice_idstr是要查询的音色 ID。
返回值：dict，包含 status、resource_link、target_model 等信息。

update_voice()

用新音频更新已有克隆音色。 
def update_voice(self, voice_id: str, url: str,
                 language_hints: List[str] = None,
                 max_prompt_audio_length: float = None,
                 enable_preprocess: bool = None) -> None
参数类型必选说明
voice_idstr是要更新的音色 ID。
urlstr是新的音频文件 URL，必须可公开访问。
language_hintsList[str]否新音频的语言提示。
max_prompt_audio_lengthfloat否预处理后的最大音频时长（秒）。
enable_preprocessbool否是否启用音频预处理。
返回值：None

delete_voice()

删除克隆音色。 
def delete_voice(self, voice_id: str) -> None
参数类型必选说明
voice_idstr是要删除的音色 ID。
返回值：None

完整示例

创建音色

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

service = VoiceEnrollmentService()

voice_id = service.create_voice(
  target_model="cosyvoice-v3-plus",
  prefix="myvoice",
  url="https://your-audio-url.wav",
  language_hints=["zh"],
  max_prompt_audio_length=15.0,
  enable_preprocess=False
)

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

查询音色列表

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

service = VoiceEnrollmentService()

voices = service.list_voice(prefix="myvoice", page_index=0, page_size=10)

print(f"Request ID: {service.get_last_request_id()}")
for voice in voices:
  print(voice)

查询音色详情

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

service = VoiceEnrollmentService()

details = service.query_voice(voice_id="cosyvoice-v3-plus-myvoice-xxxxxx")

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

更新音色

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

service = VoiceEnrollmentService()

service.update_voice(
  voice_id="cosyvoice-v3-plus-myvoice-xxxxxx",
  url="https://new-audio-url.wav"
)

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

删除音色

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService

dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'

service = VoiceEnrollmentService()

service.delete_voice(voice_id="cosyvoice-v3-plus-myvoice-xxxxxx")

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