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

## 概述

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

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

## 音频要求

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

| 项目 | 要求 |
|------|------|
| 支持格式 | WAV (16bit), MP3, M4A |
| 音频时长 | 推荐 10~20 秒，最长不得超过 60 秒 |
| 文件大小 | ≤ 10 MB |
| 采样率 | ≥ 16 kHz |
| 声道 | 单声道 / 双声道 |
| 内容 | 音频必须包含至少 5 秒连续清晰朗读（无背景音），其余部分仅允许短暂停顿（≤2 秒）；整段音频应避免背景音乐、噪音或其他人声，确保核心朗读内容质量；请使用正常说话音频作为输入，不要上传歌曲或唱歌音频，以确保复刻效果准确和可用。 |
| 语言 | 因驱动音色的语音合成模型（通过 `target_model` 参数指定）而异：<br>- cosyvoice-v2：中文（普通话）、英文<br>- 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 | 兼容旧版或低要求场景 |

#### 准备工作

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

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

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

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

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

```python
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 参考

### 创建音色

上传用于复刻的音频，创建自定义音色。

#### 接口说明

```python
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 模型

#### 请求示例

```python
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}")
```

### 查询音色列表

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

#### 接口说明

```python
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：审核不通过，不可调用
    '''
```

#### 请求示例

```python
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}")
```

#### 响应示例

```python
[
    {
        "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 | 音色状态：<br>- DEPLOYING： 审核中<br>- OK：审核通过，可调用<br>- UNDEPLOYED：审核不通过，不可调用 |

### 查询指定音色

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

#### 接口说明

```python
def query_voice(self, voice_id: str) -> List[str]:
    '''
    查询指定音色的详细信息
    
    param: voice_id 需要查询的音色ID
    return: List[str] 音色详细信息，包含状态、创建时间、音频链接等
    '''
```

#### 请求示例

```python
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}")
```

#### 响应示例

```python
{
    "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<br>必须与后续调用语音合成接口时使用的语音合成模型一致，否则合成会失败 |
| gmt_create | string | 创建音色的时间 |
| gmt_modified | string | 修改音色的时间 |
| status | string | 音色状态：<br>- DEPLOYING： 审核中<br>- OK：审核通过，可调用<br>- UNDEPLOYED：审核不通过，不可调用 |

### 更新音色

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

#### 接口说明

```python
def update_voice(self, voice_id: str, url: str) -> None:
    '''
    更新音色
    
    param: voice_id 音色id
    param: url 用于声音复刻的音频文件url
    '''
```

#### 请求示例

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

### 删除音色

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

#### 接口说明

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

#### 请求示例

```python
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：声音复刻效果不佳，有杂音或不清晰怎么办？

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

## 参考文档

- [CosyVoice 声音复刻 API](https://www.alibabacloud.com/help/zh/model-studio/cosyvoice-clone-api)
- [实时语音合成-CosyVoice](https://www.alibabacloud.com/help/zh/model-studio/text-to-speech)