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

# Suno 음성 클론 API 연동 설명

> Suno Music Generation 集成指南 - XHuoAPI

SUNO는 임의의 오디오 파일을 통해 맞춤형 음성 캐릭터를 생성하여 음악 생성에 음성 클론을 활용할 수 있습니다. 기존의 Persona API(Suno가 생성한 `audio_id` 사용)와 달리, 이 API는 공개적으로 접근 가능한 `audio_url` 즉, 사용자의 음성 녹음을 입력으로 받습니다. 본 문서는 음성 클론 API 연동 방법을 설명합니다.

## 1단계: 음성 캐릭터 생성

이 API는 세 가지 입력 파라미터를 받습니다: `audio_url`(필수), 공개적으로 접근 가능한 MP3 또는 WAV 형식의 단일 인물 명확한 음성이 포함된 오디오 파일 URL; `name`과 `description`(선택 사항)은 음성 캐릭터의 이름과 설명입니다.

**오디오 파일 요구사항:**

* 형식: MP3 또는 WAV
* 길이: 최소 10초 이상
* 내용: 단일 인물 명확한 음성, 배경 소음이나 음악은 최대한 적게

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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`로, 업로드한 오디오로 생성된 음성 캐릭터는 비공개입니다.

## 2단계: 음성 캐릭터를 사용한 음악 생성

음성 캐릭터 ID를 획득한 후, [Suno Audios Generation API](https://api.xhuoapi.ai/documents/4da95d9d-7722-4a72-857d-bf6be86036e9)를 사용해 음악을 생성할 수 있습니다. `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.xhuoapi.ai/v1/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` 액션과 함께 사용하여 클론된 음성으로 기존 곡을 리메이크하는 데도 활용할 수 있습니다.