# 阿里云CosyVoice声音复刻API说明文档
## 一、接口概述
CosyVoice声音复刻API依托大模型技术，仅需10~20秒清晰音频，即可快速生成高度拟真的定制音色（`voice_id`），支持`cosyvoice-v1`和`cosyvoice-v2`模型（v2效果更优）。复刻服务免费，使用复刻音色进行语音合成时按字符计费。

核心功能：音色的创建、查询、更新、删除，生成的`voice_id`可直接用于CosyVoice语音合成接口。

## 二、前提条件
1. 开通CosyVoice服务，获取API Key（推荐配置到环境变量，避免硬编码）。
2. 安装最新版DashScope SDK（Java/Python），其他语言需调用RESTful API。
3. 准备公网可访问的音频URL（推荐上传至阿里云OSS，支持WAV/MP3/M4A格式）。

## 三、核心接口详情（支持Java/Python SDK + RESTful API）
### 1. 创建音色（生成voice_id）
#### 功能描述
上传10~20秒音频，生成专属`voice_id`，用于后续语音合成。
#### 请求参数
| 参数名       | 类型   | 是否必填 | 说明                                                                 |
|--------------|--------|----------|----------------------------------------------------------------------|
| target_model | string | 是       | 复刻模型，支持`cosyvoice-v1`/`cosyvoice-v2`                          |
| prefix       | string | 是       | 音色自定义前缀，仅允许数字和小写字母，长度<10字符                     |
| url          | string | 是       | 音频文件公网URL，需满足格式要求（采样率≥16kHz、文件≤10MB、含≥5秒连续语音） |
#### 响应参数
| 参数名   | 类型   | 说明                     |
|----------|--------|--------------------------|
| voice_id | string | 定制音色ID，用于语音合成 |
| request_id| string | 任务唯一标识，用于排查问题 |
#### 示例代码（Python SDK）
```python
import os
import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService

dashscope.api_key = os.getenv('DASHSCOPE_API_KEY')
service = VoiceEnrollmentService()
# 调用创建接口
voice_id = service.create_voice(target_model="cosyvoice-v2", prefix="test", url="音频公网URL")
print(f"生成的voice_id: {voice_id}")
```

### 2. 查询所有音色
#### 功能描述
查询账号下已创建的所有音色，支持按前缀筛选和分页。
#### 请求参数
| 参数名     | 类型   | 是否必填 | 说明                          |
|------------|--------|----------|-------------------------------|
| prefix     | string | 否       | 音色前缀，为空则返回所有音色  |
| page_index | int    | 否       | 页码索引，默认0               |
| page_size  | int    | 否       | 每页条数，默认10              |
#### 响应参数
| 参数名       | 类型   | 说明                                                                 |
|--------------|--------|----------------------------------------------------------------------|
| voice_list   | array  | 音色列表，含每个音色的`voice_id`、创建时间（gmt_create）、状态（status） |
| status       | string | 音色状态：DEPLOYING（审核中）/OK（可用）/UNDEPLOYED（审核失败）        |
| request_id   | string | 任务唯一标识                                                         |

### 3. 查询指定音色
#### 功能描述
查询单个`voice_id`的详细信息（状态、原始音频URL等）。
#### 请求参数
| 参数名   | 类型   | 是否必填 | 说明               |
|----------|--------|----------|--------------------|
| voice_id | string | 是       | 需查询的音色ID     |
#### 响应参数
| 参数名         | 类型   | 说明                                                                 |
|----------------|--------|----------------------------------------------------------------------|
| voice_id       | string | 音色ID                                                               |
| resource_link  | string | 复刻所用音频的公网URL                                                |
| target_model   | string | 复刻时使用的模型                                                     |
| status         | string | 音色状态（DEPLOYING/OK/UNDEPLOYED）                                  |
| gmt_create     | string | 音色创建时间                                                         |

### 4. 更新音色
#### 功能描述
使用新的音频URL更新已有`voice_id`的音色。
#### 请求参数
| 参数名   | 类型   | 是否必填 | 说明                                                                 |
|----------|--------|----------|----------------------------------------------------------------------|
| voice_id | string | 是       | 需更新的音色ID                                                       |
| url      | string | 是       | 新的音频公网URL（需满足格式要求）                                     |
#### 响应参数
| 参数名     | 类型   | 说明               |
|------------|--------|--------------------|
| request_id | string | 任务唯一标识       |

### 5. 删除音色
#### 功能描述
删除无需使用的`voice_id`，释放配额（账号最多保留1000个音色）。
#### 请求参数
| 参数名   | 类型   | 是否必填 | 说明               |
|----------|--------|----------|--------------------|
| voice_id | string | 是       | 需删除的音色ID     |
#### 响应参数
| 参数名     | 类型   | 说明               |
|------------|--------|--------------------|
| request_id | string | 任务唯一标识       |

## 四、音频文件要求
1. 格式：支持WAV（16bit）、MP3、M4A。
2. 采样率：≥16000Hz。
3. 时长：10~20秒（建议不超过60秒），含至少一段≥5秒的连续语音。
4. 大小：≤10MB。
5. 质量：语音清晰、无杂音，朗读连贯。

## 五、使用流程（复刻→合成）
1. 调用「创建音色」接口，传入音频URL，获取`voice_id`。
2. 调用CosyVoice语音合成接口，将`voice_id`作为`voice`参数传入，即可使用定制音色合成语音。
3. （可选）通过「查询指定音色」接口确认`status`为`OK`后再使用。

## 六、关键限制
1. 配额限制：每个主账号最多保留1000个复刻音色，删除后释放配额。
2. 并发限制：复刻接口总并发≤10 RPS（v1+v2合计），语音合成接口并发≤3 RPS。
3. 模型匹配：v1版本`voice_id`仅用于v1合成，v2版本`voice_id`仅用于v2合成，不可混用。
4. 有效期：超过1年未使用的音色将自动下线。

## 七、常见错误码及解决方案
| 错误码                  | 说明                                  | 解决方案                                                         |
|-------------------------|---------------------------------------|------------------------------------------------------------------|
| Throttling.AllocationQuota | 音色数量达限额                        | 删除无用音色或提交工单申请扩容                                   |
| Audio.AudioShortError   | 音频有效时长过短                      | 重新录制10~20秒连续语音                                          |
| InvalidApiKey           | API Key无效                           | 检查API Key是否正确，无多余空格或缺失字符                         |
| Model.AccessDenied      | 模型访问权限不足                      | 使用“默认业务空间”下的API Key调用                                 |
| BadRequest.UnsupportedFileFormat | 音频格式不支持                  | 转换为WAV/MP3/M4A格式，确认文件实际编码与后缀一致                 |
| Audio.FileSizeExceed    | 音频文件超过10MB                      | 压缩文件大小或截取有效片段                                       |

## 八、注意事项
1. 版权要求：需对复刻音频的所有权及合法使用权负责，遵守服务协议。
2. 音频URL：确保公网可访问，推荐使用阿里云OSS生成临时访问链接（避免长期公开泄露）。
3. 升级建议：v1音色可使用原始音频重新复刻为v2版本，获得更优效果。
4. 合成调节：使用`voice_id`合成语音时，可通过`volume`（音量）、`speechRate`（语速）等参数调节输出效果。