sionrui/docs/cosyvoice-copy.md

阿里云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）

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（语速）等参数调节输出效果。