> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno声音克隆 API 对接说明

> Suno Music Generation API guide - Ace Data Cloud

SUNO允许我们通过任意音频文件创建自定义声音角色，实现声音克隆用于音乐生成。与已有的Persona API（使用Suno生成的`audio_id`）不同，该API接受一个公开可访问的`audio_url`，即你自己的人声录音。本文档讲解声音克隆API的对接方法。

## 第一步：创建声音角色

该API有三个输入参数：`audio_url`（必填），为一个公开可访问的MP3或WAV格式音频文件URL，其中包含单人清晰人声；`name`和`description`（可选），为声音角色的名称和描述。

> **音频文件要求**
>
> * 音频格式需为`WAV`或`MP3`
> * 音频时长不少于`10秒`，推荐使用`30~60秒`的干净单人干声素材
> * 音频中应包含**清晰、可辨识的单人讲话或演唱人声**
> * 请尽量避免**背景噪音、伴奏、回声、混响**
> * 不要包含**多位说话人**或**多重人声**
> * 音量过低、语音不清晰、噪声过重的素材，可能导致**克隆失败**或**生成效果较差**
>   **使用限制说明**
> * 通过上传音频创建的声音角色为**私有资源**
> * 该声音角色**不支持跨账号复用**
> * 建议在创建成功后尽快使用，长时间不使用可能出现**失效或不可用**

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/suno/voices' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "audio_url": "http://cos.aitutu.cc/mp4/ru-user-voice.mp3",
  "name": "RU User Voice Test",
  "description": "用户语音录音示例"
}'
```

结果如下：

```json theme={null}
{
  "success": true,
  "task_id": "b9150e51-d87c-4556-a55e-100947a63bdf",
  "data": {
    "persona_id": "e95013f8-eaee-4741-a42f-1d559a9d0b2b",
    "name": "RU User Voice Test",
    "is_public": false
  }
}
```

可以看到，`data`的`persona_id`字段就是创建的声音角色ID。`is_public`字段始终为`false`，因为通过上传音频创建的声音角色是私有的。

## 第二步：使用声音角色生成音乐

有了声音角色ID之后，我们便可以使用[Suno Audios Generation API](https://platform.acedata.cloud/documents/suno-audios)来进行音乐生成了。将`action`设为`generate`，并将`persona_id`设为上面返回的声音角色ID，生成的歌曲将使用克隆的声音进行演唱。

> **注意：** 声音克隆仅支持`chirp-v4-5`及以上模型（如`chirp-v4-5`、`chirp-v5`、`chirp-v5-5`），不支持`chirp-v4`。

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/suno/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "chirp-v5-5",
  "prompt": "A warm synth-pop song about city nights",
  "persona_id": "e95013f8-eaee-4741-a42f-1d559a9d0b2b"
}'
```

结果如下：

```json theme={null}
{
  "success": true,
  "task_id": "53d8a334-a972-43c5-895e-60c4454e88d5",
  "data": [
    {
      "id": "16463960-077c-4700-bbb3-3c7897b943d3",
      "title": "Soft Neon on My Skin",
      "audio_url": "https://cdn1.suno.ai/16463960-077c-4700-bbb3-3c7897b943d3.mp3",
      "image_url": "https://cdn2.suno.ai/image_16463960-077c-4700-bbb3-3c7897b943d3.jpeg",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "prompt": "A warm synth-pop song about city nights",
      "duration": 156.28
    }
  ]
}
```

可以看到，生成的歌曲使用了克隆的声音进行演唱。`persona_id`也可以与`cover`动作配合使用，用克隆的声音翻唱已有歌曲。