130 lines
8.2 KiB
Markdown
130 lines
8.2 KiB
Markdown
# 阿里云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`（语速）等参数调节输出效果。
|