CosyVoice 开发者API对接文档

前言说明

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

接口概览

模型说明

支持的模型列表

注意事项

• 创建的音色只能在指定的目标模型中使用

接口认证

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

Authorization: Bearer YOUR_API_KEY

API Key 可在:个人中心→我的密钥获取

声音克隆接口

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

接口地址

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

请求头

请求参数

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

请求头

请求参数

克隆和设计是用一个接口，当提供 voice_prompt 和 preview_text 时，自动切换为声音设计模式。

声音描述示例

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

响应示例

{
  "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

请求头

请求参数

响应示例（非流式）

{
  "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

请求头

请求参数

权限说明

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

请求示例

POST https://www.yuntts.com/api/v1/cosyvoice-delete-voice
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
    "voice_id": "yuntts-xxx"
}

响应示例

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

更新音色

⚠️ 注意: 仅限声音复刻音色，声音设计音色不支持更新。

接口信息

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

请求头

 请求参数

请求示例

POST https://www.yuntts.com/api/v1/cosyvoice-update-voice
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY

{
    "voice_id": "yuntts-xxx",
    "file": [二进制音频文件]
}

系统音色

系统音色请查看《CosyVoice 系统音色列表》

计费说明

字符计费规则

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

模型价格（元/万字符）

错误码说明

常见问题

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

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

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

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

Q: 合成失败会扣费吗？

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

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

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