> ## 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( S uno가 생성한 `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 오디오 생성 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": "도시의 밤에 대한 따뜻한 신스팝 노래",
  "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": "도시의 밤에 대한 따뜻한 신스팝 노래",
      "duration": 156.28
    }
  ]
}
```

생성된 곡이 클론된 음성을 사용하여 노래하는 것을 확인할 수 있습니다. `persona_id`는 `cover` 동작과 함께 사용하여 클론된 음성으로 기존 곡을 리메이크하는 데에도 사용할 수 있습니다.