CosyVoice 开发者API对接文档

前言说明

CosyVoice 声音复刻服务依托生成式语音大模型，仅需 10–20 秒音频样本，即可生成高度相似、自然流畅的定制音色，无需传统训练流程。声音设计支持通过文本描述生成专属音色，可自定义多语言及多维度音色特征，适用于广告配音、角色塑造、有声内容创作等场景。声音复刻 / 设计与语音合成为前后衔接的两个环节，本文档重点说明声音复刻 / 设计相关参数及语音合成接口详情。

接口概览

模型说明

支持的模型列表

注意事项

• 声音设计 支持 v3 和 v3.5 系列模型（v3-plus、v3-flash、v3.5-plus、v3.5-flash）
• 本文档不涉及实时语音合成功能
• 创建的音色只能在指定的目标模型中使用

接口认证

所有接口都需要在请求头中携带 API Key：

Authorization: Bearer YOUR_API_KEY

API Key 可在网站主题设置中获取。

声音克隆接口

通过上传音频文件或提供音频 URL 来创建自定义音色。

接口地址

POST https://www.yuntts.com/api/v1/cosyvoice-create-voice

请求格式

使用 multipart/form-data 格式

请求参数

language_hints 参数说明

该参数用于辅助模型识别样本音频（原始参考音频）的语种，从而更准确地提取音色特征，提升复刻效果。若设置的语言提示与实际音频语言不符（例如为中文音频设置 en），系统将忽略此提示，并依据音频内容自动检测语言。

取值范围（因模型而异）：

音频文件要求

• 支持格式：MP3、WAV、M4A
• 文件大小：最大 10MB
• 音频时长：建议 10-30 秒
• 音频质量：建议 16kHz 以上采样率

响应示例

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "voice_id": "yuntts_xxxxxx",
    "model": "cosyvoice-v3.5-plus",
    "name": "我的音色",
    "created_at": "2024-01-01 12:00:00"
  }
}

错误响应

{
  "code": 400,
  "message": "错误信息"
}

声音设计接口

通过文字描述来设计自定义音色。

接口地址

POST https://www.yuntts.com/api/v1/cosyvoice-create-voice

请求格式

使用 application/json 格式

请求参数

声音描述示例

• "温柔的女声，像主持人一样专业"
• "低沉有磁性的男声，适合讲故事"
• "活泼开朗的童声"
• "成熟稳重的中年男声"

响应示例

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "voice_id": "yuntts_xxxxxx",
    "model": "cosyvoice-v3.5-plus",
    "name": "我的音色",
    "created_at": "2024-01-01 12:00:00"
  }
}

语音合成接口

使用指定的模型和音色进行语音合成。

接口地址

POST https://www.yuntts.com/api/v1/cosyvoice-synthesize

请求格式

使用 application/json 格式

请求参数

响应示例

{
  "code": 200,
  "message": "语音合成成功",
  "data": {
    "audio": {
      "url": "https://example.com/audio.mp3",
      "sample_rate": 22050,
      "format": "mp3"
    }
  },
  "char_count": 100,
  "cost": 0.01
}

响应字段说明

删除音色接口

删除已创建的自定义音色。

接口地址

POST https://www.yuntts.com/api/v1/cosyvoice-delete-voice

请求格式

使用 application/json 格式

请求参数

权限说明

• 只有音色创建者和管理员可以删除
• 删除前会验证权限

响应示例

{
  "code": 200,
  "message": "删除成功"
}

计费说明

字符计费规则

• 汉字按 2 个字符计算
• 其他字符（英文、数字、符号等）按 1 个字符计算

模型价格（元/万字符）

会员折扣

• 永久会员: 8 折
• VIP会员: 9 折

免费额度

• 仅会员用户可享受
• 每月免费额度可在后台设置
• 免费额度用完后正常计费

最低扣费

• 每次合成最低扣费 0.01 元

计费流程

1. 计算字符数
2. 根据模型计算基础费用
3. 应用会员折扣
4. 使用免费额度（如有）
5. 扣除余额（如需要）
6. 调用 API
7. 失败自动退款

错误码说明

代码示例

JavaScript - 声音克隆

const formData = new FormData();
formData.append('name', '我的音色');
formData.append('target_model', 'cosyvoice-v3.5-plus');
formData.append('file', audioFile);

fetch('https://www.yuntts.com/api/v1/cosyvoice-create-voice', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
})
.then(res => res.json())
.then(data => console.log(data));

JavaScript - 声音设计

const params = {
  name: '我的音色',
  target_model: 'cosyvoice-v3.5-plus',
  voice_prompt: '温柔的女声',
  preview_text: '欢迎使用我们的声音设计服务'
};

fetch('https://www.yuntts.com/api/v1/cosyvoice-create-voice', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify(params)
})
.then(res => res.json())
.then(data => console.log(data));

JavaScript - 语音合成

const params = {
  model: 'cosyvoice-v3.5-plus',
  voice: 'longxiaochun',
  text: 'Hello World',
  speech_rate: 1.0
};

fetch('https://www.yuntts.com/api/v1/cosyvoice-synthesize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify(params)
})
.then(res => res.json())
.then(data => {
  if (data.code === 200) {
    const audio = new Audio(data.data.audio.url);
    audio.play();
  }
});

Python - 语音合成

import requests

url = "https://www.yuntts.com/api/v1/cosyvoice-synthesize"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "cosyvoice-v3.5-plus",
    "voice": "longxiaochun",
    "text": "Hello World"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

常见问题

Q: 声音克隆和声音设计有什么区别？

A: 声音克隆需要上传音频文件，声音设计只需要文字描述。声音设计仅支持 v3.5 系列模型。

Q: 创建的音色可以在其他模型中使用吗？

A: 不可以，创建音色时指定的目标模型决定了该音色只能在哪个模型中使用。

Q: 合成失败会扣费吗？

A: 不会，合成失败会自动退款。

Q: 免费额度是每月重置吗？

A: 是的，免费额度每月初自动重置。