> ## 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 整合指南 - Ace Data Cloud

SUNO 允許我們通過任意音頻文件創建自定義聲音角色，實現聲音克隆用於音樂生成。與已有的 Persona API（使用 Suno 生成的 `audio_id`）不同，該 API 接受一個公開可訪問的 `audio_url`，即你自己的人聲錄音。本文檔講解聲音克隆 API 的對接方法。

## 第一步：創建聲音角色

該 API 有三個輸入參數：`audio_url`（必填），為一個公開可訪問的 MP3 或 WAV 格式音頻文件 URL，其中包含單人清晰人聲；`name` 和 `description`（可選），為聲音角色的名稱和描述。

> **音頻文件要求**
>
> * 音頻格式需為 `WAV` 或 `MP3`
> * 音頻時長需在 `10~240 秒` 之間，推薦使用 `30~60 秒` 的乾淨單人乾聲素材
> * 音頻中應包含**清晰、可辨識的單人講話或演唱人聲**
> * 請務必避免**背景噪音、伴奏、回聲、混響**；帶伴奏的完整歌曲通常無法通過聲紋校驗
> * 不要包含**多位說話人**或**多重人聲**
> * 音量過低、語音不清晰、噪聲過重的素材，可能導致**克隆失敗**或**生成效果較差**
>   **使用限制說明**
> * 通過上傳音頻創建的聲音角色為**私有資源**
> * 該聲音角色**不支持跨賬號復用**
> * 建議在創建成功後儘快使用，長時間不使用可能出現**失效或不可用**
> * 返回的 `name` 由系統自動生成，請以返回的 `persona_id` 為準

> **調用失敗時請先重試**
> 聲音克隆為算力密集型任務，即使素材完全合規也存在一定概率的偶發失敗，常見返回如
> `voices_sound_different`（聲紋校驗未通過）等。**這類失敗與音頻質量無關，使用同一素材重試通常即可成功**，
> 建議在集成時對失敗結果實現 1\~2 次自動重試。失敗的請求不會計費。

```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": "https://cdn.acedata.cloud/suno_demo.mp3",
  "name": "My Voice",
  "description": "單人清晰人聲示例"
}'
```

> 上述 `https://cdn.acedata.cloud/suno_demo.mp3` 為可直接調用的示例素材（MP3，41 秒，單人乾聲）。
> 如需 `WAV` 格式示例，可使用
> `https://cdn.acedata.cloud/uploads/82d23b97-ec1c-4b41-91b8-989fc51f8765`（WAV，41 秒，單聲道 44.1kHz）。

結果如下：

```json theme={null}
{
  "success": true,
  "task_id": "0fa609a6-c8d9-4bb5-8574-e4c93bb55d02",
  "data": {
    "persona_id": "1ab79a71-a229-4350-8f02-402ff02eac16",
    "name": "VOICE_20260803037676",
    "is_public": false
  }
}
```

可以看到，`data` 的 `persona_id` 字段就是創建的聲音角色 ID。`is_public` 字段始終為 `false`，因為通過上傳音頻創建的聲音角色是私有的。注意返回的 `name` 為系統自動生成，後續請使用 `persona_id` 引用該聲音角色。

## 第二步：使用聲音角色生成音樂

有了聲音角色 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": "1ab79a71-a229-4350-8f02-402ff02eac16"
}'
```

結果如下：

```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` 動作配合使用，用克隆的聲音翻唱已有歌曲。