> ## 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

AI의 활용이 확대됨에 따라 다양한 AI 프로그램이 점차 보급되고 있습니다. AI는 사람들의 업무와 생활 전반에 점차 깊이 들어오고 있습니다. 또한 AI가 관련된 산업도 점점 더 많아지고 있으며, 초기의 글쓰기부터 의료 교육, 그리고 현재의 음악에 이르기까지 다양합니다.

Suno는 전문적이고 고품질의 AI 노래 및 음악 창작 플랫폼으로, 사용자는 간단한 텍스트 프롬프트만 입력하면 장르 스타일과 가사에 따라 보컬이 포함된 노래를 생성할 수 있습니다. 이 AI 음악 생성기는 Meta, TikTok, Kensho 등 유명 기술 기업 출신의 팀원들이 개발했으며, 어떠한 악기 도구도 필요 없이 모든 사람이 아름다운 음악을 창작할 수 있도록 하는 것을 목표로 합니다.

다음은 모델 업데이트 진행 상황입니다:

| 버전 | model | 출시 시간 | lyric 제한 | style 제한 | 노래 최대 길이 |
| - | - | - | - | - | - |
| v6 | chirp-v6 | 2026.09.09 | — | — | — |
| v6 Wild | chirp-v6-wild | 2026.09.09 | — | — | — |
| v6 Mini | chirp-v6-mini | 2026.09.09 | — | — | — |
| v5.5 | chirp-v5-5 | 2026.03.27 | 5000 | 1000 | 8분 |
| v5 | chirp-v5 | 2025.09.23 | 5000 | 1000 | 8분 |
| v4.5+ | chirp-v4-5-plus | 2025.07.17 | 5000 | 1000 | 8분 |
| v4.5 | chirp-v4-5 | 2025.05.03 | 5000 | 1000 | 4분 |
| v4 | chirp-v4 | 2024.12.17 | 3000 | 200 | 150초 |
| v3.5 | chirp-v3-5 | --- | 3000 | 200 | 120초 |

> 위 표의 `lyric` 및 `style` 제한은 사용자 정의 모드(`custom`이 `true`)에서의 상한입니다. 사용자 정의가 아닌 영감 모드(`custom`이 `false`)에서는 `prompt`만 입력하며, 길이 상한은 500자입니다(모든 모델 동일).

Suno는 현재 `chirp-v6`, `chirp-v6-wild` 및 `chirp-v6-mini`를 지원합니다. `chirp-v6` 사용을 권장하며, 이전 모델 이름도 계속 호환됩니다.

그러나 Suno 공식은 API를 제공하지 않으며, AceDataCloud는 Suno의 API 세트를 제공하여 Suno 공식 연동을 시뮬레이션하고, 원하는 음악을 편리하고 빠르게 생성할 수 있습니다.

## 신청 및 사용

Suno Audios Generation API를 사용하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)에서 API Token을 발급받아 예비용으로 보관하세요.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

아직 로그인하거나 등록하지 않았다면 로그인 페이지로 자동 이동하여 등록 및 로그인을 안내하며, 완료 후 현재 페이지로 자동 돌아옵니다.

**하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 서비스별로 별도 신청할 필요가 없습니다.** 최초 신청 시 무료 크레딧이 제공되어 무료로 체험할 수 있으며, 크레딧이 부족할 경우 [콘솔](https://platform.acedata.cloud/console/coin)에서 범용 잔액을 충전할 수 있습니다.

> 📘 전체 문서: [Suno Audios Generation API →](https://platform.acedata.cloud/documents/suno-audios)

## 기본 사용

어떤 노래를 생각하든 임의의 문단을 입력할 수 있습니다. 예를 들어 크리스마스에 관한 노래를 생성하고 싶다면 `a song for Christmas`를 입력하면 되며, 그림과 같습니다:

![](https://cdn.acedata.cloud/2kuuup.png)

여기서 Request Headers를 설정한 것을 볼 수 있으며, 다음을 포함합니다:

* `accept`: 어떤 형식의 응답 결과를 받을지 지정하며, 여기서는 `application/json`, 즉 JSON 형식으로 입력합니다.
* `authorization`: API를 호출하는 키이며, 신청 후 직접 드롭다운에서 선택할 수 있습니다.

또한 Request Body를 설정했으며, 다음을 포함합니다:

* `action`: 오디오 작업 유형이며, 기본값은 `generate`입니다. 생성, 이어쓰기, 커버, 연결, 스템 분리, 오디오 트랙 추가, 지정 오디오 트랙 추출, 음향 효과 생성 및 속도 조정 등의 작업을 지원하며, 모두 `POST /suno/audios`를 통해 호출합니다.
* `prompt`: Suno 공식 영감 모드 프롬프트(`custom`이 `false`일 때 적용)이며, 최대 500자입니다.
* `model`: 이번 음악 생성 작업의 모델입니다. v6 시리즈에는 `chirp-v6`, `chirp-v6-wild`, `chirp-v6-mini`가 포함되며, 이전 모델 이름도 계속 호환됩니다.
* `max_mode`: 강화 생성 모드입니다. `generate`는 `custom`과 `max_mode`가 모두 `true`일 때만 활성화되며, 비용은 1.12 Credits입니다. `add_stem`은 직접 활성화할 수 있으며, 비용은 1.344 Credits입니다. 비활성화하거나 생략할 경우 비용은 각각 0.56 및 0.672 Credits입니다.
* `variety`: 생성 결과의 다양성 강도로, `off`, `normal`, `high`, `extra`, `max` 중에서 선택할 수 있습니다. `generate` 및 `add_stem`에만 사용되며, 다른 action에서 전달하면 400이 반환됩니다.
* `lyric`: Suno 공식 사용자 지정 모드의 가사 내용입니다. `chirp-v3-5` 및 `chirp-v4`는 최대 3000자이며, `chirp-v4-5` 이상(`chirp-v5`, `chirp-v5-5` 포함)은 최대 5000자입니다.
* `custom`: 사용자 지정 모드를 사용할지 여부이며, 기본값은: `false`입니다.
* `instrumental`: Suno 공식 영감 모드의 순수 음악 옵션입니다.
* `title`: Suno 공식 사용자 지정 모드의 음악 제목입니다. `chirp-v3-5`, `chirp-v4`는 최대 80자이며, `chirp-v4-5` 이상은 최대 100자입니다.
* `style`: Suno 공식 사용자 지정 모드 음악 스타일입니다. `chirp-v3-5` 및 `chirp-v4`는 최대 200자이며, `chirp-v4-5` 이상(`chirp-v5`, `chirp-v5-5` 포함)은 최대 1000자입니다.
* `negative_tags`: 사용자 지정 모드(`custom`이 `true`)에서 생성 결과에서 제외하고 싶은 음악 스타일 또는 장르입니다.
* `audio_weight`: 오디오 또는 음성 특징의 영향 가중치이며, 범위는 0-1이고 `0`도 유효한 값입니다. 생성, 이어쓰기, 커버, 오디오 트랙 추가 및 음성 일관성 등의 작업에 사용할 수 있으며, 참조 오디오 또는 음성 특징이 없을 경우 모델이 이 값을 약화하거나 무시할 수 있습니다.
* `audio_id`: 참조 음악의 ID입니다.
* `overpainting_start`/`overpainting_end`: 기존 순수 음악에 보컬을 추가하는 시작 및 종료 시간이며, 단위는 초입니다.
* `underpainting_start`/`underpainting_end`: 아카펠라에 반주를 추가하는 시작 및 종료 시간이며, 단위는 초입니다.
* `persona_id`: 아티스트의 노래 ID입니다.
* `continue_at`: 이어쓰기 경계이며, 단위는 초입니다. 예를 들어, 213.5는 3분 33.5초 지점부터 후속 구간 생성을 시작함을 의미합니다. `lyric`과 `style`은 경계 이후의 새 콘텐츠만 안내하며, 소스 오디오에서 경계 이전의 가사나 보컬을 대체하지 않습니다.
* `style_influence`: 사용자 지정 모드에서의 스타일 영향력이며, 범위는 0-1입니다. 값이 클수록 일반적으로 선택한 스타일에 더 부합하며, `0`도 유효한 값으로 전달됩니다.
* `replace_section_end`: 교체 구간의 최종 시간입니다.
* `replace_section_start`: 교체 구간의 시작 시간입니다.
* `vocal_gender`: 남성/여성 보컬 선호를 제어하며, 여성 보컬은 `f`, 남성 보컬은 `m`이고, 4.5 이상 모델에서 유효합니다. 선호 항목이므로 엄격한 준수가 보장되지는 않습니다.
* `weirdness`: 사용자 지정 모드에서의 기이함 정도이며, 범위는 0-1입니다. 값이 클수록 일반적으로 더 창의적이고 실험적이며, `0`도 유효한 값으로 전달됩니다.
* `duration`: 기대하는 노래 길이이며, 단위는 초이고 정수여야 하며, 값 범위는 10에서 360입니다. 이 매개변수는 사용자 지정 모드(`custom`이 `true`)의 노래 생성에 사용됩니다. 이는 하드 제약이 아닌 경향성 프롬프트입니다. 모델이 이를 참고하지만 달성을 보장하지 않으며, 실제 결과물 길이는 응답의 `duration` 필드를 기준으로 하고 일반적으로 기대값보다 짧습니다.

### 고급 매개변수 적용 범위

| 매개변수 | 값 | 지원되는 action | 설명 |
| - | - | - | - |
| `weirdness` | 0-1 | 선택 사항 | 실험성을 조절하며, `0`은 유효한 값입니다. 효과는 작업, 모드 및 모델에 따라 달라집니다 |
| `style_influence` | 0-1 | 선택 사항 | 스타일 준수 경향을 조절하며, `0`은 유효한 값입니다. 효과는 작업, 모드 및 모델에 따라 달라집니다 |
| `audio_weight` | 0-1 | 선택 사항 | 오디오 또는 음성 특징의 영향을 조절하며, 참조 정보가 없으면 모델이 무시할 수 있습니다 |
| `variety` | `off` / `normal` / `high` / `extra` / `max` | `generate`, `add_stem` | 결과 간 스타일 다양성을 조절합니다 |
| `max_mode` | boolean | `generate`(`custom=true` 필요), `add_stem` | 일관성을 강화하고 강화 모드 기준으로 과금됩니다 |
| `vocal_gender` | `f` / `m` | 보컬 제어를 지원하는 생성 작업 | 선호 항목이며, 엄격한 준수가 보장되지는 않습니다 |
| `duration` | 정수 10-360 | 선택 사항 | 기대 길이이며, 구체적인 작업, 모드 또는 모델에서 무시할 수 있습니다 |

플랫폼은 매개변수 유형과 값 범위를 검증하지만, action이 다르다는 이유만으로 이러한 선택적 조절 항목을 거부하지는 않습니다. 구체적인 효과는 작업, 모드 및 모델에 따라 결정됩니다.

* `lyric_prompt`: 가사 생성을 위한 prompt이며, `custom`이 `true`이고 `lyric`이 전달되지 않았을 때에만 적용됩니다.
* `callback_url`: 결과 콜백이 필요한 URL입니다.
* `async`: 선택 사항이며, `true`로 설정하면 인터페이스가 즉시 `task_id`를 반환합니다. `callback_url`을 제공할 필요가 없으며, 이후 해당 작업 조회 인터페이스를 통해 폴링하여 결과를 가져옵니다.

생성된 코드는 다음과 같습니다:

![](https://cdn.acedata.cloud/1xehwl.png)

「Try」 버튼을 클릭하여 API를 직접 테스트할 수 있으며, 1-2분 정도 기다리면 결과는 다음과 같습니다:

```json theme={null}
{
  "success": true,
  "task_id": "e72fb249-bd5b-4e2a-b20c-8a06fea5ac14",
  "trace_id": "7dbc5b6a-b2c0-4d85-9d39-fa8a8a785ccf",
  "data": [
    {
      "id": "b481b17a-bf50-4e10-8adc-4d5635050893",
      "title": "겨우살이 아래에서",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-001",
      "lyric": "[절]\n땅 위로 눈송이가 내리고\n반짝이는 불빛이 사방에 가득해\n솔향기가 공기를 채우고\n어디에나 크리스마스의 마법이 있어\n[후렴]\n오늘 밤 겨우살이 아래에서\n부드러운 달빛 속에 빛나는 마음들\n웃음소리가 울려 퍼지고\n기분은 밝아\n크리스마스 시간이야\n너무나 딱 맞는 느낌이야\n[절 2]\n벽난로의 빛 곁에 걸린 양말들\n찬 바람이 부는 동안 안은 따뜻해\n쿠키가 구워지고\n달콤한 기쁨\n밝게 빛나는 기쁨의 계절\n[후렴]\n오늘 밤 겨우살이 아래에서\n부드러운 달빛 속에 빛나는 마음들\n웃음소리가 울려 퍼지고\n기분은 밝아\n크리스마스 시간이야\n너무나 딱 맞는 느낌이야\n[브리지]\n촛불 아래에서 부르는 캐럴\n위의 별들이 세상을 가깝게 느끼게 해\n평화와 사랑\n계절의 신조\n우리에게 필요한 모든 것으로 마음을 채워\n[후렴]\n오늘 밤 겨우살이 아래에서\n부드러운 달빛 속에 빛나는 마음들\n웃음소리가 울려 퍼지고\n기분은 밝아\n크리스마스 시간이야\n너무나 딱 맞는 느낌이야",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T15:59:32.468Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "크리스마스를 위한 노래",
      "style": "홀리데이, 경쾌한, 남성 보컬",
      "duration": 154.92
    },
    {
      "id": "fbf22dab-5e2b-4e02-84c0-6d7605f14c3d",
      "title": "겨우살이 아래에서",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-002",
      "lyric": "[절]\n땅 위로 눈송이가 내리고\n반짝이는 불빛이 사방에 가득해\n솔향기가 공기를 채우고\n어디에나 크리스마스의 마법이 있어\n[후렴]\n오늘 밤 겨우살이 아래에서\n부드러운 달빛 속에 빛나는 마음들\n웃음소리가 울려 퍼지고\n기분은 밝아\n크리스마스 시간이야\n너무나 딱 맞는 느낌이야\n[절 2]\n벽난로의 빛 곁에 걸린 양말들\n찬 바람이 부는 동안 안은 따뜻해\n쿠키가 구워지고\n달콤한 기쁨\n밝게 빛나는 기쁨의 계절\n[후렴]\n오늘 밤 겨우살이 아래에서\n부드러운 달빛 속에 빛나는 마음들\n웃음소리가 울려 퍼지고\n기분은 밝아\n크리스마스 시간이야\n너무나 딱 맞는 느낌이야\n[브리지]\n촛불 아래에서 부르는 캐럴\n위의 별들이 세상을 가깝게 느끼게 해\n평화와 사랑\n계절의 신조\n우리에게 필요한 모든 것으로 마음을 채워\n[후렴]\n오늘 밤 겨우살이 아래에서\n부드러운 달빛 속에 빛나는 마음들\n웃음소리가 울려 퍼지고\n기분은 밝아\n크리스마스 시간이야\n너무나 딱 맞는 느낌이야",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T15:59:32.468Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "크리스마스를 위한 노래",
      "style": "홀리데이, 경쾌한, 남성 보컬",
      "duration": 158.48
    }
  ]
}
```

이때 두 곡의 내용을 얻을 수 있으며, 제목, 미리보기 이미지, 가사, 오디오, 비디오 등의 내용을 포함합니다.

필드 설명은 다음과 같습니다:

* success：생성 성공 여부이며, 성공하면 `true`, 그렇지 않으면 `false`입니다.
* data：생성된 노래의 상세 정보를 포함하는 목록입니다.
  * state： 노래 생성 상태이며, 주로 다음 네 가지를 포함합니다:
    * succeeded：생성 성공
    * pending：대기열에 있음
    * running：실행 중
    * error：실패
  * id：노래 ID
  * title：노래 제목
  * image\_url：노래의 커버 이미지
  * lyric：노래 가사
  * audio\_url：노래의 최종 오디오 주소입니다. 플랫폼은 Ace Data Cloud CDN 주소를 우선 반환하며, 영구 저장에 실패할 경우 원본 미디어 주소를 반환할 수 있으므로 즉시 다운로드하세요.
  * video\_url：노래의 비디오 파일이며, 열면 mp4 비디오입니다.
  * created\_at：생성 시간
  * model：사용된 모델이며, 일반적으로 최신 v3 모델입니다.
  * style：스타일

## 사용자 지정 생성

가사를 사용자 지정하여 생성하려면 가사를 입력할 수 있습니다:

이때 `lyric` 필드에는 다음과 유사한 내용을 전달할 수 있습니다:

```
[Verse]\nSnowflakes falling all around\nGlistening white\nCovering the ground\nChildren laughing\nFull of delight\nIn this winter wonderland tonight\nSanta's sleigh\nUp in the sky\nRudolph's nose shining bright\nOh my\nHear the jingle bells\nRinging so clear\nBringing joy and holiday cheer\n[Verse 2]\nRoasting chestnuts by the fire's glow\nChristmas lights\nThey twinkle and show\nFamilies gathering with love and cheer\nSpreading warmth to everyone near
```

> 참고로, 여기 가사에서 `\n`은 줄바꿈 문자입니다. 가사를 생성하는 방법을 모른다면 AceDataCloud에서 제공하는 가사 생성 API를 사용하여 prompt를 통해 가사를 생성할 수 있으며, API는 [Suno Lyrics Generation API](https://platform.acedata.cloud/documents/suno-lyrics)입니다.

다음으로 가사, 제목, 스타일에 따라 노래를 사용자 지정 생성하려면 다음 내용을 지정할 수 있습니다:

* lyric：가사 텍스트
* custom：`true`로 입력하며, 사용자 지정 생성을 의미합니다. 이 매개변수의 기본값은 false이며, `prompt`를 사용하여 생성함을 의미합니다.
* title：노래 제목입니다.
* style：노래 스타일이며, 선택 사항입니다.

입력 예시는 다음과 같습니다:

![](https://cdn.acedata.cloud/qp3iba.png)

입력을 완료하면 다음과 같이 코드가 자동 생성됩니다:

![](https://cdn.acedata.cloud/o5haei.png)

해당 코드는 다음과 같습니다:

```shell 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",
  "prompt": "A song for Christmas",
  "model": "chirp-v4-5",
  "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
  "custom": true
}'
```

테스트가 허용되며, 생성 효과는 유사합니다.

## 사용자 지정 가수 스타일 생성 기능

가수 스타일을 사용하여 노래를 생성하려면, 먼저 위의 기본 사용법을 통해 노래를 생성합니다.\
마지막으로 이 노래를 가수 스타일로 설정해야 하며, 이후 [Suno Persona API](https://platform.acedata.cloud/documents/suno-persona)에 들어가 공식적으로 생성된 음악 ID `audio_id`를 기반으로 가수 스타일의 id 매개변수 `persona_id`를 생성해야 합니다. 구체적인 매개변수는 아래 그림과 같습니다:

![](https://cdn.acedata.cloud/pmzo3l.png)

작성 완료 후 자동으로 생성된 코드는 다음과 같습니다:

![](https://cdn.acedata.cloud/a5g0nj.png)

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/persona"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
    "name": "test"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

실행을 클릭하면 다음과 같은 결과를 얻을 수 있습니다:

```json theme={null}
{
  "success": true,
  "task_id": "7628b754-4fe7-4e79-bda4-806d0dd8bf6e",
  "data": {
    "persona_id": "e0d7319e-aa2a-44cb-b00a-916218d7cb0b"
  }
}
```

위의 `audio_id`와 `persona_id`를 각각 `97efc9f4-0e8d-4b3e-88df-14568fa1b11f`, `e0d7319e-aa2a-44cb-b00a-916218d7cb0b`로 하여 이번 예제 데이터로 사용합니다. 그런 다음 매개변수 `action`을 `artist_consistency`로 설정할 수 있으며(새 버전의 가수 스타일 Persona-v2-vox인 경우, `action`은 반드시 `artist_consistency_vox`로 설정해야 합니다), 계속 생성해야 하는 노래의 ID와 가수 스타일 ID를 입력합니다. 작성 예시는 다음과 같습니다:

![](https://cdn.acedata.cloud/fukijq.png)

작성 완료 후 자동으로 생성된 코드는 다음과 같습니다:

![](https://cdn.acedata.cloud/5uzk9d.png)

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "artist_consistency",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "persona_id": "e0d7319e-aa2a-44cb-b00a-916218d7cb0b",
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

실행을 클릭하면 다음과 같은 결과를 얻을 수 있습니다:

```json theme={null}
{
  "success": true,
  "task_id": "9b732b1a-bd67-48bc-95e4-90140e06836f",
  "trace_id": "30fcd88e-7687-4137-92d7-913b58115204",
  "data": [
    {
      "id": "727a36e2-8dce-4df7-99e5-14e44635c80f",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-003",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:27:33.979Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 244.4
    },
    {
      "id": "3b33301a-b17e-4b25-8842-09b46dab1a36",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-004",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:27:33.979Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 229.88
    }
  ]
}
```

결과 내용이 위의 내용과 일치하는 것을 볼 수 있으며, 이를 통해 가수 스타일을 사용하여 노래를 생성하는 기능을 구현할 수 있습니다.

## 계속 생성 기능

이미 생성된 Suno 노래를 계속 생성하려면 매개변수 `action`을 `extend`로 설정하고, 계속 생성해야 하는 노래의 ID를 입력할 수 있습니다. 노래 ID는 기본 사용법에 따라 획득하며, 위의 내용에서 이때 노래의 ID는 다음과 같음을 알 수 있습니다:

```
"id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f"
```

> 참고로 여기의 가사 중 `id`는 생성 후 노래의 ID입니다. 노래를 생성하는 방법을 모르는 경우, 위의 기본 사용법을 참고하여 노래를 생성할 수 있습니다.

직접 업로드한 노래를 계속 생성하려면 매개변수 `action`을 `upload_extend`로 설정하고, 계속 생성해야 하는 사용자 지정 업로드 노래의 ID를 입력할 수 있습니다. 노래 ID는 [Suno Upload Generation API](https://platform.acedata.cloud/documents/suno-upload)를 사용하여 획득하며, 아래 그림과 같습니다:

![](https://cdn.acedata.cloud/a0mn5e.png)

다음으로 이어 쓸 구간의 가사를 반드시 작성해야 하며, 스타일을 지정할 수 있습니다:

* lyric: `continue_at` 이후 새로 생성되는 구간의 가사를 안내하는 용도로만 사용되며, 원본 오디오에서 해당 시점 이전의 가사를 대체하지 않습니다.
* custom: `true`로 작성하면 사용자 지정 생성을 의미하며, 이 매개변수의 기본값은 false로, `prompt`를 사용하여 생성함을 의미합니다.
* style: 이어 쓸 구간의 노래 스타일이며, 선택 사항입니다.
* continue\_at: 이어 쓰기 경계이며, 단위는 초입니다. 예를 들어, 213.5는 3분 33.5초 지점부터 후속 구간을 생성함을 의미합니다.

> `extend`는 기존 노래를 이어서 뒤로 창작하는 용도이며, 노래 전체의 가사를 바꾸는 것이 아닙니다. 노래 전체를 처음부터 새 가사로 만들고 싶다면 `generate`를 사용하여 다시 생성하십시오. 기존 노래를 참고하여 다시 연주하고 싶다면 `cover`를 사용할 수 있습니다. 새로운 전체 가사를 전달하더라도, `continue_at` 이전의 원래 가사는 여전히 대체되지 않습니다.

작성 예시는 다음과 같습니다:

![](https://cdn.acedata.cloud/zp9s42.png)

작성 완료 후 자동으로 생성된 코드는 다음과 같습니다:

![](https://cdn.acedata.cloud/wwpw78.png)

아래에는 실제 과거 호출 스냅샷이 보존되어 있으며, 이 중 `continue_at`은 2초이므로 처음 2초만 이어쓰기 경계 이전의 원본 내용에 해당합니다. 실제로 곡의 끝부분에 가까운 지점에서 이어쓰기할 때는 이 값을 이어쓰기를 시작할 것으로 기대하는 초 수로 설정하고, `lyric`에는 경계 이후에 부를 새 구절만 제공해야 합니다.

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
    "continue_at": 2,
    "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
    "custom": True,
    "instrumental": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

실행을 클릭하면 다음과 같은 결과를 얻을 수 있습니다:

```json theme={null}
{
  "success": true,
  "task_id": "75b835d9-30d1-4641-8524-0aeedbdc9e1a",
  "trace_id": "44c41045-a2e1-4d19-aafc-7abd239d0d5c",
  "data": [
    {
      "id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-005",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:38:35.509Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 165.92
    },
    {
      "id": "4334c5b4-0a44-4b26-a8f6-66cc4dbb8fc3",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-006",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:38:35.509Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 158.84
    }
  ]
}
```

결과에서 `lyric`은 이번 이어쓰기 작업에 사용된 가사 텍스트를 반환하는 것을 알 수 있습니다. 이 필드는 완성된 전체 오디오의 축자 전사가 아닙니다. `extend`의 경우 `continue_at` 이전의 원본 오디오는 여전히 원래 가사를 사용하며, 새 가사는 이어쓰기 구간을 안내하는 데만 사용됩니다.

## 완성된 노래 가져오기

현재 모델의 `extend` 결과에는 일반적으로 `continue_at` 이전의 원본 오디오와 경계 이후의 새 내용이 이미 포함되어 있으므로, 먼저 반환된 오디오의 실제 길이와 내용을 기준으로 이미 완성된 노래인지 판단해야 합니다. 반환된 것이 독립적인 이어쓰기 조각이거나 여러 번의 이어쓰기 이력을 명시적으로 하나의 노래로 병합해야 하는 경우에만 연결 기능을 사용합니다:

* action: 내용은 `concat`입니다.
* audio\_id: 마지막 이어쓰기 조각의 ID입니다.

예를 들어 확장된 노래 ID가 0a1e1b10-c36a-41c9-9bfb-b26d9d25db98인 경우, 다음과 같이 매개변수를 설정할 수 있습니다:

```json theme={null}
{
  "action": "concat",
  "audio_id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98"
}
```

다른 매개변수는 변경하지 않으며, 반환되는 것은 완성된 한 곡의 노래, 즉 모든 노래 조각을 연결한 결과입니다. 단, 결과는 한 곡만 반환되며, 예시는 다음과 같습니다:

```json theme={null}
{
  "success": true,
  "task_id": "0f794915-8418-4124-93f5-b7eb3a417167",
  "trace_id": "62afcce0-e7e5-44b8-8c2e-4bba12a4f414",
  "data": [
    {
      "id": "0efec7e0-11bf-4313-9981-2c0e7218d7dd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-007",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near\n[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:43:06.718Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 167.91997916666668,
      "concat_history": [
        {
          "continue_at": 2,
          "id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
          "infill": false,
          "source": "web",
          "type": "gen"
        },
        {
          "id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98"
        }
      ]
    }
  ]
}
```

## 음악 커버

기존 노래를 기반으로 계속 노래를 생성한 후 반환된 노래의 스타일이 적절하지 않을 수 있습니다. 이전에 생성한 노래(사용자가 직접 업로드한 음악도 지원)의 커버가 필요하다면 음악 커버 방법을 사용하면 되며, 다음 내용을 지정할 수 있습니다:

* action: 내용은 `cover`이며, 사용자가 직접 업로드한 음악에 커버 작업을 수행하는 경우 반드시 내용으로 `upload_cover`를 지정해야 합니다.
* audio\_id: 이전에 생성한 노래의 ID.

예를 들어 이전에 생성된 노래의 ID가 `0a1e1b10-c36a-41c9-9bfb-b26d9d25db98`인 경우, 다음과 같이 매개변수를 설정할 수 있습니다:

```json theme={null}
{
  "action": "cover",
  "audio_id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98",
  "prompt": "A song for Christmas",
  "model": "chirp-v4-5"
}
```

다른 매개변수는 변경되지 않으며, 반환되는 것은 커버된 노래, 즉 이전에 생성된 노래를 커버한 결과입니다. 예시는 다음과 같습니다:

```json theme={null}
{
  "success": true,
  "task_id": "b9d43d06-2e0a-4b5e-9e0d-7dfab32e00ab",
  "trace_id": "6c5e567d-0fdc-4c44-9b36-4090d9a75ff5",
  "data": [
    {
      "id": "6988fa57-f810-41cf-afab-7838db2c77dc",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-008",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:44:13.007Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 182.4
    },
    {
      "id": "ce98b991-0258-4f05-8245-e43d4efa8fb8",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-009",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:44:13.007Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 179.72
    }
  ]
}
```

생성된 결과는 위 내용과 유사하며, 이로써 이전에 생성된 노래의 커버 생성 과정이 완료됩니다.

## 구간 교체

노래를 생성한 후 노래 구간을 교체하는 별도의 작업으로 2차 창작을 해야 하는 경우, 노래의 특정 구간을 교체할 수 있습니다.

> ⚠️ **주의**: `replace_section_result_mode`의 기본값은 `full_song`입니다. 시스템은 새로 생성된 2개의 후보를 각각 이어 붙이고, 완전한 노래 2곡을 반환합니다. 아직 이어 붙이지 않은 교체 구간 후보만 필요한 경우, 명시적으로 `candidates`로 설정한 후 후보를 선택하여 [음악 이어 붙이기](#음악-이어-붙이기)를 호출하십시오.

매개변수 설명은 다음과 같습니다:

* action: 내용은 `replace_section`입니다.
* audio\_id: 원본 노래(교체되는 소스 노래)의 ID입니다.
* model: 노래 생성 모델입니다.
* lyric: 교체 후의 전체 가사(교체된 구간 및 그 컨텍스트를 포함하며, `prompt`의 내용과 일치).
* prompt: 교체해야 하는 해당 구간의 새 가사입니다.
* style: 노래의 스타일이며, 선택 사항입니다.
* replace\_section\_start: 원곡에서 교체되는 구간의 시작 시간(초)입니다.
* replace\_section\_end: 원곡에서 교체되는 구간의 종료 시간(초)입니다.
* replace\_section\_result\_mode: 반환 모드이며, 기본값은 `full_song`입니다. `full_song`은 2개의 후보를 각각 이어 붙여 완전한 노래 2곡을 반환하고, `candidates`는 아직 이어 붙이지 않은 후보 구간 2개를 반환합니다.

### 1단계: 구간 교체 작업 시작

예를 들어 이전에 생성된 노래의 ID가 `18db7ed0-2b8a-41db-91c1-b0781dcca0d4`(길이 94.12초)이고, 30초부터 60초까지의 후렴을 새 가사로 교체하려는 경우, 다음과 같이 매개변수를 설정할 수 있습니다:

```json theme={null}
{
  "action": "replace_section",
  "audio_id": "18db7ed0-2b8a-41db-91c1-b0781dcca0d4",
  "model": "chirp-v5-5",
  "custom": false,
  "instrumental": false,
  "lyric": "[인트로]\n징과 북 소리 요란하고 붉은 등불 높이 걸렸네\n[벌스 1]\n폭죽 소리 속에 묵은해를 보내고\n따스한 봄바람 온 집안에 들어오네\n세뱃돈에 웃음꽃 피어나고\n황금 뱀이 춤추며 새봄을 축하하네\n[코러스]\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n[벌스 2]\n만두 향기 나는 설날 저녁 식사\n등불 흔들리며 가족의 상봉을 비추네",
  "prompt": "매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네",
  "replace_section_start": 30.0,
  "replace_section_end": 60.0,
  "replace_section_result_mode": "full_song"
}
```

기본적으로 두 후보를 각각 이어 붙여 완성한 전체 노래 2곡을 반환합니다. `replace_section_result_mode`를 `candidates`로 설정하면, 아직 이어 붙이지 않은 교체 구간 2개를 반환하며 구조는 아래 예시와 같습니다:

```json theme={null}
{
  "success": true,
  "task_id": "dd067075-a295-4160-8375-d5504327d55b",
  "trace_id": "c34f589b-9195-4d0b-af78-9c890e77609c",
  "data": [
    {
      "id": "364f9d8b-ca25-463b-9a5e-d0b7139e2d6a",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-010",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-011",
      "lyric": "[인트로]\n징과 북 소리 요란하고 붉은 등불 높이 걸렸네\n[벌스 1]\n폭죽 소리 속에 묵은해를 보내고\n따스한 봄바람 온 집안에 들어오네\n세뱃돈에 웃음꽃 피어나고\n황금 뱀이 춤추며 새봄을 축하하네\n[코러스]\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n[벌스 2]\n만두 향기 나는 설날 저녁 식사\n등불 흔들리며 가족의 상봉을 비추네",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-05-06T06:55:00.000Z",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "style": "",
      "duration": 45.16
    },
    {
      "id": "fae966ea-5f7f-4e80-9962-1c57963c7f8a",
      "title": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "duration": 33.8
    }
  ]
}
```

`candidates` 모드에서 반환되는 두 오디오의 길이(45.16초, 33.8초)는 원곡(94.12초)보다 훨씬 짧습니다. 이들은 소량의 컨텍스트를 포함한 교체 구간이며, **전체 노래가 아닙니다**. 만족스러운 후보를 선택하여 계속 수동으로 이어 붙일 수 있습니다. 기본 `full_song` 모드는 두 번의 이어 붙이기를 완료하여 전체 노래 2곡을 직접 반환합니다.

### 전체 노래 직접 반환

전체 노래를 직접 얻으려면 1단계에서 `replace_section_result_mode`를 `full_song`으로 설정할 수 있습니다. 인터페이스는 두 후보를 각각 이어 붙여 전체 노래 2곡을 반환합니다. 이 경우 `concat`을 다시 호출할 필요가 없습니다.

### 2단계: 교체 구간을 원곡에 다시 이어 붙이기

위에서 선택한 구간(예: `364f9d8b-ca25-463b-9a5e-d0b7139e2d6a`)에 대해 [음악 이어 붙이기](#음악-이어-붙이기) 섹션의 방법에 따라 `concat` 작업을 시작합니다:

```json theme={null}
{
  "action": "concat",
  "audio_id": "364f9d8b-ca25-463b-9a5e-d0b7139e2d6a",
  "model": "chirp-v5-5"
}
```

이어 붙여진 전체 노래가 반환되며, 예시는 다음과 같습니다:

```json theme={null}
{
  "success": true,
  "task_id": "5dbd4a78-0197-4ef3-9c16-8bddaf4f0c94",
  "trace_id": "580bd1da-2ad3-4d75-be1f-6c14bd4b489d",
  "data": [
    {
      "id": "365a9640-0452-4567-80f0-4f5a2a17ddd5",
      "title": "새해 복 많이 받으세요",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-012",
      "lyric": "[인트로]\n징과 북 소리 요란하고 붉은 등불 높이 걸렸네\n[벌스 1]\n폭죽 소리 속에 묵은해를 보내고\n따스한 봄바람 온 집안에 들어오네\n세뱃돈에 웃음꽃 피어나고\n황금 뱀이 춤추며 새봄을 축하하네\n[코러스]\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n매화 피어나 봄기운이 온 땅에 가득하네\n[벌스 2]\n만두 향기 나는 설날 저녁 식사\n등불 흔들리며 가족의 상봉을 비추네",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-05-06T06:56:46.057Z",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "style": "전통 중국 설날, 축제 분위기, 여성 보컬, 경쾌함",
      "duration": 105.28
    }
  ]
}
```

이때 `duration`은 이미 완전한 곡 길이(105.28초, 원곡 길이와 거의 동일)로 복원되었으며, `audio_url`이 가리키는 것은 교체가 완료된 전체 곡입니다. 이로써 "생성 → 세그먼트 교체 → 전체 곡 연결"의 2차 창작 프로세스가 완료됩니다.

## 보컬 및 반주 분리

곡 생성 후 반주와 보컬을 별도로 조작하는 2차 창작이 필요한 경우, 순수 음악 반주와 아카펠라 보컬을 분리할 수 있습니다. 다음 내용을 지정하면 됩니다:

* action: 내용은 `stems`입니다.
* audio\_id: 이전에 생성한 곡의 ID입니다.

예를 들어 이전에 생성된 곡의 ID가 ec13e502-d043-4eb2-92ee-e900c6da69d1인 경우, 다음과 같이 매개변수를 설정할 수 있습니다:

```json theme={null}
{
  "action": "stems",
  "audio_id": "ec13e502-d043-4eb2-92ee-e900c6da69d1"
}
```

위 매개변수를 통해 보컬 및 반주 분리 결과를 얻을 수 있으며, 결과는 다음과 같습니다:

```json theme={null}
{
  "success": true,
  "task_id": "4050affc-f8a6-4cba-a86c-bf201eed053d",
  "trace_id": "5107ee58-687d-422f-9195-fa0e82e1fcc8",
  "data": [
    {
      "id": "e3de0928-085a-42c4-b982-3b24738d1989",
      "title": "Deck the Sky - Vocals",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-013",
      "lyric": "[Verse]\nSnowflakes dance on rooftops high\nChildren's laughter fills the sky\nCarols ring from church bells loud\nHolidays a joyful crowd\n[Verse 2]\nCandy canes and cocoa warm\nWrapped up tight in our own storm\nStockings hung with dreams and cheer\nMagic growing every year\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright\n[Verse 3]\nFireside tales of long ago\nReindeer prance in icy glow\nEvergreen and tinsel’s gleam\nChristmas time a lovely dream\n[Bridge]\nHearts are full with friends and kin\nMistletoe for love to win\nGifts of love and hope we share\nChristmas spirit everywhere\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001",
      "created_at": "2025-01-05T07:49:16.881Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    },
    {
      "id": "ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb",
      "title": "Deck the Sky - Instrumental",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-014",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002",
      "created_at": "2025-01-05T07:49:16.892Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    }
  ]
}
```

생성된 결과는 위 내용과 유사하며, 이로써 이전에 생성한 곡에 대한 보컬 및 반주 분리 과정이 완료됩니다.

## 전체 트랙 보컬 및 반주 분리

곡 생성 후 전체 트랙 보컬 및 반주 분리 작업이 필요한 경우, 다음 내용을 지정하면 됩니다:

* action: 내용은 `all_stems`입니다.
* audio\_id: 이전에 생성한 곡의 ID입니다.

예를 들어 이전에 생성된 곡의 ID가 bdf23a5a-59f5-4103-b452-054a824a7f9f인 경우, 다음과 같이 매개변수를 설정할 수 있습니다:

```json theme={null}
{
  "action": "all_stems",
  "audio_id": "bdf23a5a-59f5-4103-b452-054a824a7f9f"
}
```

위 매개변수를 통해 전체 트랙 보컬 및 반주 분리 결과를 얻을 수 있으며, 결과는 다음과 같습니다:

```json { theme={null}
  "success": true,
  "task_id": "f4b16fb9-8478-4857-88c7-b9a1f0bb9518",
  "trace_id": "9c560ebd-4fc6-4bdb-988a-8890160a92fb",
  "data": [
    {
      "id": "f86ca64a-9519-4ea7-a592-52438e001412",
      "title": "安全之弦 (Vocals)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-015",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "99e649a7-a394-47b9-a915-d7f847285a36",
      "title": "安全之弦 (Backing Vocals)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-016",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "6d710bf7-809f-4fdc-bb63-b8cb3a456d42",
      "title": "安全之弦 (Drums)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-017",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "e05f07e3-7d80-4713-8e51-7f176c733543",
      "title": "안전의 현 (베이스)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-018",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "93fe7cd8-62fd-4739-b78e-142c7e0b8562",
      "title": "안전의 현 (기타)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-019",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "8367d71c-fdd3-441c-8ebe-70c33cca821b",
      "title": "안전의 현 (키보드)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-020",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "28c03590-731c-416e-8fd3-95cdb3d75043",
      "title": "안전의 현 (타악기)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-021",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "3d4c1a28-4e1c-485a-8201-d21bb93aca2f",
      "title": "안전의 현 (현악기)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-022",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "b9db8ded-01ec-4e37-b8a5-64aab3a814c2",
      "title": "안전의 현 (신스)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-023",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "10a5248e-32e6-42b9-8da1-678a8a392aef",
      "title": "안전의 현 (FX)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-024",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "2d272128-111f-4901-8f62-5ae1eb43095a",
      "title": "안전의 현 (브라스)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-025",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "4a7c19a5-f8d4-4e4a-add9-aa0bad9307cc",
      "title": "안전의 현 (목관악기)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-026",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "1ca774f9-3e75-48a6-941b-808875eadcd2",
      "title": "안전의 현 (보컬)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-027",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "14c5ffc7-addf-4fee-afd2-4b8b3e7ee470",
      "title": "안전의 현 (백킹 보컬)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-028",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "성공",
      "duration": 154.92
    }, {
      "id": "9d044557-450d-48ab-90dc-8eaf6f1cdb6c",
      "title": "안전의 현 (드럼)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-029",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "성공",
      "duration": 154.92
    }, {
      "id": "efd052d0-c12f-47b3-8282-1f3ef7610e1f",
      "title": "안전의 현 (베이스)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-030",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "성공",
      "duration": 154.92
    }, {
      "id": "5775372b-292e-4420-96ef-60e57a60cc1f",
      "title": "안전의 현 (기타)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-031",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "성공",
      "duration": 154.92
    }, {
      "id": "dab3f220-19cd-408e-9b96-30ec18f5b049",
      "title": "안전의 현 (키보드)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-032",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "성공",
      "duration": 154.92
    }, {
      "id": "2d0cd6d4-af82-4bb5-86fe-d92bdb367157",
      "title": "안전의 현 (퍼커션)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-033",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "성공",
      "duration": 154.92
    }, {
      "id": "f3191a1a-5e8d-4afe-b638-3add222d52cd",
      "title": "안전의 현 (현악기)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-034",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "성공",
      "duration": 154.92
    }, {
      "id": "a8834ea5-200b-4206-a812-9780ef336660",
      "title": "안전의 현 (신시사이저)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-035",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "성공",
      "duration": 154.92
    }, {
      "id": "f50d1a31-ef72-400a-b8ae-0367849d007d",
      "title": "안전의 현 (효과음)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-036",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "성공",
      "duration": 154.92
    }, {
      "id": "cb581673-23cc-40d6-9f9b-0f76720f0d18",
      "title": "안전의 현 (브라스)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-037",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "성공",
      "duration": 154.92
    },
{
      "id": "d91cfb52-f0a3-4546-bf8a-2ad14c3775a5",
      "title": "안전의 현 (Woodwinds)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-038",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }
  ]
}
```

생성된 결과는 위와 유사하며, 이로써 이전에 생성된 노래에 대해 보컬과 반주를 분리하는 과정이 완료됩니다.

## 오디오 트랙 추가

`add_stem`은 지정된 오디오에 대상 악기 또는 보컬 트랙을 생성하며, `POST /suno/audios`를 통해 호출합니다.

* 필수: `action`, `audio_id`, `stem_type`.
* 선택: `model`, `prompt`, `title`, `style`, `negative_tags`, `weirdness`, `style_influence`, `audio_weight`, `max_mode`, `variety`.
* 과금: 일반 모드 0.672 Credits, `max_mode`가 `true`일 때 1.344 Credits.

```json theme={null}
{
  "action": "add_stem",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "stem_type": "bass",
  "model": "chirp-v6",
  "prompt": "Add warm bass guitar",
  "style": "minimal piano pulse with warm bass guitar",
  "negative_tags": "vocals",
  "variety": "normal",
  "max_mode": false,
  "async": true
}
```

최종 상태 응답:

```json theme={null}
{
  "success": true,
  "task_id": "82851953-9590-4334-8bb8-ae30ccadc815",
  "trace_id": "862bbcce-1678-44ff-982d-8b439c126a5e",
  "data": [
    {
      "id": "0adc26ca-2720-4c69-b237-457a986d70e3",
          "audio_url": "https://cdn.acedata2.cloud/suno/0adc26ca-2720-4c69-b237-457a986d70e3.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 12.8
    },
    {
      "id": "e2d39a6c-1d20-4a40-adaf-b2551815d869",
          "audio_url": "https://cdn.acedata2.cloud/suno/e2d39a6c-1d20-4a40-adaf-b2551815d869.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 12.36
    }
  ],
  "cost": {"amount": 0.6048, "currency": "credit", "list_amount": 0.672}
}
```

## 오디오 트랙 추출

`extract_stem`은 지정된 오디오에서 대상 오디오 트랙을 추출하는 동시에, 해당 트랙을 제거한 보완 버전을 반환하며, `POST /suno/audios`를 통해 호출합니다.

* 필수: `action`, `audio_id`, `stem_type`.
* 선택: `audio_format`, 현재 공개 듀얼 채널 규약은 `mp3`만 지원합니다.
* 과금: 1.12 Credits.

```json theme={null}
{
  "action": "extract_stem",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "stem_type": "bass",
  "audio_format": "mp3",
  "async": true
}
```

최종 상태 응답의 `data`는 평면 오디오 목록을 유지하며, `stem_sets`는 대상 오디오 트랙과 보완 오디오 트랙의 대응 관계를 나타냅니다:

```json theme={null}
{
  "success": true,
  "task_id": "ae9557d0-4ff7-4a35-bcde-d881e78fbfe5",
  "trace_id": "82c51a55-7627-41a5-b72b-1b9775ca25f2",
  "data": [
    {"id":"3084d7e1-4278-4733-8b56-56f7ecf3f859","title":"(Bass)","audio_url":"https://cdn.acedata2.cloud/suno/3084d7e1-4278-4733-8b56-56f7ecf3f859.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":1},
    {"id":"19b83ca9-a51d-494f-a41d-5b0957f3295e","title":"(Without Bass)","audio_url":"https://cdn.acedata2.cloud/suno/19b83ca9-a51d-494f-a41d-5b0957f3295e.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":1},
    {"id":"7eb431e8-f4db-4915-902e-0e89d2b3185a","title":"(Bass)","audio_url":"https://cdn.acedata2.cloud/suno/7eb431e8-f4db-4915-902e-0e89d2b3185a.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":2},
    {"id":"495d29cc-5790-4d0a-8b95-9551a6127b61","title":"(Without Bass)","audio_url":"https://cdn.acedata2.cloud/suno/495d29cc-5790-4d0a-8b95-9551a6127b61.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":2}
  ],
  "stem_sets": [
    {"stem_type":"bass","isolated":{"id":"3084d7e1-4278-4733-8b56-56f7ecf3f859","state":"succeeded","stem_set":1},"remainder":{"id":"19b83ca9-a51d-494f-a41d-5b0957f3295e","state":"succeeded","stem_set":1}},
    {"stem_type":"bass","isolated":{"id":"7eb431e8-f4db-4915-902e-0e89d2b3185a","state":"succeeded","stem_set":2},"remainder":{"id":"495d29cc-5790-4d0a-8b95-9551a6127b61","state":"succeeded","stem_set":2}}
  ],
  "cost": {"amount": 1.008, "currency": "credit", "list_amount": 1.12}
}
```

## 음향 효과 생성

`sounds`는 텍스트 설명에 따라 일회성 또는 반복 가능한 음향 효과를 생성하며, `POST /suno/audios`를 통해 호출합니다.

* 필수: `action`, `sound`, `sound_type`.
* 선택: `model`, `bpm`, `key`, `audio_format`; `audio_format`은 현재 `mp3`만 지원합니다.
* `sound_type`: `one-shot` 또는 `loop`.
* 과금: 0.112 Credits.

```json theme={null}
{
  "action": "sounds",
  "sound": "single soft analog synth pluck, no reverb",
  "sound_type": "one-shot",
  "model": "chirp-v6",
  "bpm": 120,
  "key": "C",
  "audio_format": "mp3",
  "async": true
}
```

```json theme={null}
{
  "success": true,
  "task_id": "f6716546-d118-40a0-ad15-09999f9f22ba",
  "trace_id": "da4c7895-e494-4bd8-83bd-132e006c94e3",
  "data": [
    {"id":"b3cd3e7d-96e4-48ef-abde-73c7ddee8b4a","title":"single soft analog synth pluck, no reverb","audio_url":"https://cdn.acedata2.cloud/suno/b3cd3e7d-96e4-48ef-abde-73c7ddee8b4a.mp3","model":"chirp-v6","state":"succeeded","duration":10},
    {"id":"f1517867-b76a-4cdf-b006-9ce6e653e0a5","title":"single soft analog synth pluck, no reverb","audio_url":"https://cdn.acedata2.cloud/suno/f1517867-b76a-4cdf-b006-9ce6e653e0a5.mp3","model":"chirp-v6","state":"succeeded","duration":10}
  ],
  "cost": {"amount": 0.1008, "currency": "credit", "list_amount": 0.112}
}
```

## 오디오 속도 조정

`adjust_speed`는 지정한 오디오의 재생 속도를 조정하며, `POST /suno/audios`를 통해 호출합니다.

* 필수: `action`, `audio_id`, `speed_multiplier`, `title`.
* 선택 사항: `keep_pitch`.
* `speed_multiplier`: 범위 0.25–4.
* 과금: 0.28 Credits.

```json theme={null}
{
  "action": "adjust_speed",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "speed_multiplier": 1.1,
  "keep_pitch": true,
  "title": "Suno contract verification speed 1.1x",
  "async": true
}
```

원본 오디오 길이는 9.8초이며, 1.1배속 결과는 8.909090909초입니다:

```json theme={null}
{
  "success": true,
  "task_id": "c5860fdd-76b1-40a1-b5b5-ec047e471c8a",
  "trace_id": "292ed097-3631-441c-ac80-52f326b62726",
  "data": [
    {
      "id": "02534b52-45a7-4961-834a-f473a407e62c",
      "title": "Suno contract verification speed 1.1x",
      "audio_url": "https://cdn.acedata2.cloud/suno/02534b52-45a7-4961-834a-f473a407e62c.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 8.909090909090908
    }
  ],
  "cost": {"amount": 0.252, "currency": "credit", "list_amount": 0.28}
}
```

생성 모델에는 무작위성이 있습니다. 인터페이스는 파라미터 의미, 작업 상태 및 응답 구조의 일관성을 보장하지만, 서로 다른 요청에서 완전히 동일한 파형이 생성되는 것은 보장하지 않습니다.

## 사용자 지정 생성의 고급 파라미터

공식적으로 사용자 지정 모드에서 고급 파라미터 `weirdness`==>`Weirdness`, `style_influence`==>`Style Influence`, `audio_weight`==>`Audio Influence`를 사용하여 생성할 수 있으며, 이에 해당하는 공식 예시는 다음과 같습니다:

![](https://cdn.acedata.cloud/1xonxy.png)

이 중 고급 파라미터의 범위는 모두 0-1 사이이며, 구체적인 파라미터는 아래 그림과 같습니다:

![](https://cdn.acedata.cloud/7i94ih.png)

입력을 완료하면 다음과 같은 코드가 자동으로 생성됩니다:

![](https://cdn.acedata.cloud/2dlbo6.png)

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "generate",
    "model": "chirp-v4-5",
    "lyric": "Hello Hello Hello ",
    "custom": True,
    "weirdness": 0.4,
    "style_influence": 0.4,
    "audio_weight": 0.4
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

실행을 클릭하면 다음과 같은 결과를 얻을 수 있습니다:

```json theme={null}
{
  "success": true,
  "task_id": "2f3aa682-e1a7-43a9-9fbb-ed0ce8668a4b",
  "trace_id": "07408194-7deb-4a52-a36d-9a9a13143b5f",
  "data": [
    {
      "id": "c66e2077-7580-43f2-9937-c67a8afcd8bd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-039",
      "lyric": "Hello Hello Hello ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-07-10T12:54:35.199Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 187.92
    },
    {
      "id": "a922f97b-307c-4c4d-aae3-a47ba8202a10",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-040",
      "lyric": "Hello Hello Hello ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-07-10T12:54:35.199Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 229.64
    }
  ]
}
```

이렇게 고급 파라미터를 사용하여 사용자 지정 노래를 생성했으며, 결과는 위와 유사합니다.

## 노래 길이 제어

기본적으로 생성되는 노래의 길이는 모델이 자체적으로 결정하며, 일반적으로 30초에서 4분 사이입니다. 더 길거나 짧은 결과물이 필요한 경우 `duration` 파라미터를 통해 원하는 길이를 지정할 수 있으며, 단위는 초이고 값은 10에서 360 사이의 정수입니다.

이 파라미터는 사용자 지정 모드(`custom`이 `true`인 경우)의 노래 생성에 사용됩니다. 특히 설명할 점은 `duration`이 **강제 제약이 아닌, 경향성 힌트**라는 것입니다: 모델은 생성 시 이 값을 참고하지만, 도달을 보장하지 않으며, 실제 테스트에서 실제 길이는 보통 기대값보다 현저히 짧고 동일한 요청에서 반환되는 두 노래의 길이도 몇 배 차이 날 수 있습니다. 완전히 동일한 요청이라도 여러 번 제출하여 얻는 길이에는 큰 차이가 있을 수 있습니다. 따라서 이를 정확한 길이 제어로 사용하지 말고, 비즈니스상 고정 길이가 필요한 경우 결과물을 받은 후 직접 잘라내거나 재시도하십시오.

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "generate",
    "model": "chirp-v5-5",
    "custom": True,
    "title": "Under the City Lights",
    "style": "lo-fi piano",
    "lyric": "[Verse]\nSunrise creepin\nGold on the floor\n[Chorus]\nUnder the city lights\n",
    "duration": 330
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

주의할 점은 요청의 `duration`은 **기대 길이**이고, 응답 `data`에서 각 곡의 `duration` 필드는 해당 곡의 **실제 길이**라는 것입니다. 두 이름은 같지만 의미는 다르며, 실제 길이가 기대값과 같다고 보장되지 않습니다. 가사 길이는 완성본 길이에 영향을 미치는 주요 요인 중 하나이므로, 더 긴 완성본이 필요하다면 더 완전한 가사를 함께 제공하는 것을 권장합니다.

인터페이스는 `duration`이 10에서 360 사이의 정수여야 하는지 검증합니다. 이는 여전히 생성 목표일 뿐이며, 완성본 길이를 보장하지는 않습니다.

## Add Insterumental 기능

2025년 8월 suno에 새로운 Add Insterumental 기능이 출시되었습니다. 먼저 무반주 무보컬 노래 한 곡을 업로드해야 하며, suno가 반주를 추가하도록 할 수 있습니다. 먼저 [Suno Upload API](https://platform.acedata.cloud/documents/suno-upload)에서 무반주 무보컬 노래 한 곡을 업로드할 수 있으며, 해당 작업은 아래 그림과 같습니다:

![](https://cdn.acedata.cloud/fxl914.png)

그런 다음 업로드 후의 `audio_id`를 기록해야 하며, 구체적인 결과는 아래 그림과 같습니다:

![](https://cdn.acedata.cloud/47t6wj.png)

마지막으로 `audio_id` 하나를 얻었습니다: 92254cab-3372-4d9e-bce9-cdcfdbc39070. 그런 다음 아래 매개변수도 입력해야 합니다:

* action: 값은 `underpainting`입니다.
* underpainting\_start: 업로드한 노래에 반주를 추가하는 시작 시간이며, 기본값은 0입니다.
* underpainting\_end: 업로드한 노래에 반주를 추가하는 종료 시간이며, 노래의 총 길이보다 작아야 합니다.
* audio\_id: 업로드한 무반주 무보컬 노래의 ID입니다.
* style: 반주의 스타일이며, 반주이므로 가사를 사용하지 않는 것이 좋습니다.

입력을 완료하면 아래와 같이 코드가 자동으로 생성됩니다:

![](https://cdn.acedata.cloud/8x1ic6.png)

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "underpainting",
    "model": "chirp-v4-5",
    "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
    "audio_id": "92254cab-3372-4d9e-bce9-cdcfdbc39070",
    "underpainting_end": 120
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

실행을 클릭하면 아래와 같은 결과를 얻는 것을 확인할 수 있습니다:

```json theme={null}
{
  "success": true,
  "task_id": "822d2e14-c535-4d48-a4e5-1b6ab00b04a7",
  "trace_id": "257eac2c-8e4f-44d0-8454-5e215111eefa",
  "data": [
    {
      "id": "2788cd21-bd84-422d-beb5-859c60fbf5b6",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-041",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:25:42.548Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
      "duration": 10.16
    },
    {
      "id": "a4bb7220-e971-4cbf-a626-b86c648bcf55",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-042",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:25:42.548Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
      "duration": 2.52
    }
  ]
}
```

이렇게 하면 업로드한 무반주 무보컬 노래에 반주를 추가하는 작업이 완료되며, 결과는 위 내용과 유사합니다.

## Add Vocals 기능

2025년 8월 suno에 새로운 Add Vocals 기능이 출시되었습니다. 먼저 순수 음악 한 곡을 업로드해야 하며, suno가 가사를 작성하고 보컬 노래를 생성하도록 할 수 있습니다. 먼저 [Suno Upload API](https://platform.acedata.cloud/documents/suno-upload)에서 무반주 무보컬 노래 한 곡을 업로드할 수 있으며, 해당 작업은 아래 그림과 같습니다:

![](https://cdn.acedata.cloud/fxl914.png)

그런 다음 업로드 후의 `audio_id`를 기록해야 하며, 구체적인 결과는 아래 그림과 같습니다:

![](https://cdn.acedata.cloud/47t6wj.png)

마지막으로 `audio_id` 하나를 얻었습니다: 92254cab-3372-4d9e-bce9-cdcfdbc39070. 그런 다음 아래 매개변수도 입력해야 합니다:

* action: 값은 `overpainting`입니다.
* overpainting\_start: 업로드한 노래에 보컬을 추가하는 시작 시간이며, 기본값은 0입니다.
* overpainting\_end: 업로드한 노래에 보컬을 추가하는 종료 시간이며, 노래의 총 길이보다 작아야 합니다.
* audio\_id: 업로드한 무반주 무보컬 노래의 ID입니다.
* custom: 이 모드에서는 반드시 사용자 정의 모드를 사용하여 가사를 입력해야 합니다.
* lyric: 사용자 정의 모드에서 입력하는 가사입니다.
* style: 반주의 스타일입니다.

입력을 완료하면 아래와 같이 코드가 자동으로 생성됩니다:

![](https://cdn.acedata.cloud/a4pbes.png)

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "overpainting",
    "model": "chirp-v4-5",
    "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
    "custom": True,
    "audio_id": "92254cab-3372-4d9e-bce9-cdcfdbc39070",
    "overpainting_end": 120
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

실행을 클릭하면 다음과 같은 결과를 얻을 수 있습니다:

```json theme={null}
{
  "success": true,
  "task_id": "31bb250e-6614-49ec-ac85-631f224daeba",
  "trace_id": "efe8e7f3-9a65-4f13-a9f8-51e8478899df",
  "data": [
    {
      "id": "a597f945-64df-4722-a631-d436450832bd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-043",
      "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:33:51.550Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 105.32
    },
    {
      "id": "b41a8b91-3d88-4ebd-a6cf-732764b24954",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-044",
      "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:33:51.550Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 148.16
    }
  ]
}
```

이렇게 업로드한 무반주 무보컬 노래에 보컬을 추가하는 작업이 완료되며, 결과는 위와 유사합니다.

## Remaster 기능

2025년 12월 Suno에서 새롭게 Remaster 기능을 출시했습니다. 이 기능은 노래를 다시 생성할 수 있으며, 계정 간 사용은 불가능합니다. 또한 다음과 같은 매개변수를 입력해야 합니다:

* action: 내용은 `remaster`입니다.
* audio\_id: 다시 생성해야 하는 노래 ID입니다.
* model: v4.5+, v5만 지원합니다.
* variation\_category: v5 이상 버전에서만 지원하며, 값은 high, normal, subtle 세 가지뿐입니다.

입력을 완료하면 다음과 같은 코드가 자동으로 생성됩니다:

![](https://cdn.acedata.cloud/7h4zmw.png)

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "remaster",
    "variation_category": "high",
    "audio_id": "21fd46d4-45c3-4826-bec9-3f3df667902e"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

실행을 클릭하면 다음과 같은 결과를 얻을 수 있습니다:

```json theme={null}
{
  "success": true,
  "task_id": "791ee74c-9363-4352-afe7-babb19b89899",
  "trace_id": "77acda57-c3d4-4e11-a506-4f50e0609916",
  "data": [
    {
      "id": "b0515cdf-9cb5-46cd-b0fe-10a239dc9274",
      "title": "Navidad en costura  (Remastered)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-045",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-046",
      "lyric": "En Teror las clases siguen,\nni en Navidad hay parón;\ncose el grupo entre villancicos\ny un buen trocito de turrón.\nLa Popular abre sus puertas,\ny el taller suena mejor;\nhilo, aguja y canto alegre\nlo pasaremos mejor\nSeguimos en las costuras,\ncon música y diversión;\nlos alumnos comeremos\nGolosinas un montón ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-12-04T13:09:59.936Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Villancico",
      "duration": 32.2
    },
    {
      "id": "06edab94-a4f9-4c0c-abac-a2e8a97c76a8",
      "title": "Navidad en costura  (Remastered)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-047",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-048",
      "lyric": "En Teror las clases siguen,\nni en Navidad hay parón;\ncose el grupo entre villancicos\ny un buen trocito de turrón.\nLa Popular abre sus puertas,\ny el taller suena mejor;\nhilo, aguja y canto alegre\nlo pasaremos mejor\nSeguimos en las costuras,\ncon música y diversión;\nlos alumnos comeremos\nGolosinas un montón ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-12-04T13:09:59.936Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Villancico",
      "duration": 32.2
    }
  ]
}
```

이렇게 이미 생성된 노래를 다시 생성하는 작업이 완료되며, 결과는 위와 유사합니다.

## Mashup 믹스곡 생성 기능

2025년 12월 Suno에서 새롭게 Mashup 기능을 출시했습니다. 이 기능은 두 개의 참고 노래를 기반으로 노래를 생성할 수 있으며, 또한 다음과 같은 매개변수를 입력해야 합니다:

* action: 내용은 `mashup`입니다.
* mashup\_audio\_ids: 두 개의 참고 노래 ID입니다.
  작성 완료 후 다음과 같이 코드가 자동 생성됩니다:

![](https://cdn.acedata.cloud/8mo82l.png)

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "mashup",
    "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
    "model": "chirp-v4-5",
    "custom": True,
    "instrumental": False,
    "mashup_audio_ids": ["9f102969-0024-479e-b38f-c0c5db21383d","6aebb715-701c-433f-b976-a7ff5cf16255"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

실행을 클릭하면 다음과 같은 결과를 얻을 수 있습니다:

```json theme={null}
{
  "success": true,
  "task_id": "3fe070eb-2ab1-4424-909c-acfe3ca761af",
  "trace_id": "2b220382-7a84-4853-ae43-05cdcad233a9",
  "data": [
    {
      "id": "5ff751dc-0e72-4de9-a54b-2cad50984b47",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-049",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-050",
      "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-25T15:13:30.181Z",
      "model": "chirp-v4-5",
      "state": "succeeded",
      "style": "",
      "duration": 219.08
    },
    {
      "id": "19c515c4-d7b3-4a17-8ab0-dd1ebd4861b8",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-051",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-052",
      "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-25T15:13:30.181Z",
      "model": "chirp-v4-5",
      "state": "succeeded",
      "style": "",
      "duration": 163.12
    }
  ]
}
```

이렇게 참조 곡을 믹싱하여 생성하는 작업이 완료되며, 결과는 위와 유사합니다.

## Samples 샘플링으로 곡 생성

여기서의 `samples`는 단일 오디오 구간 샘플링입니다. 기존 오디오에서 시작 및 종료 시간을 선택하고, 해당 구간을 샘플 소재로 사용하여 창작합니다. 이는 아래에서 1\~4개의 완전한 참조 오디오 구간을 사용하는 Inspo 영감 창작 기능과는 다릅니다. 다음 매개변수를 입력해야 합니다:

* action: 내용은 `samples`입니다.
* samples\_start: 샘플링 시작 시간입니다.
* samples\_end: 샘플링 종료 시간입니다.
* audio\_id: 샘플링할 참조 곡의 ID입니다.

작성 완료 후 다음과 같이 코드가 자동 생성됩니다:

![](https://cdn.acedata.cloud/vkzumz.png)

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "samples",
    "model": "chirp-v5",
    "lyric": "[Verse 1]\\nPhone lit up\\nHeadline in my hand\\nFeels made up\\nStill says “you won’t understand”\\nYour name\\nMy name\\nSide by side in the scroll\\nCold black text\\nOn a story I used to hold\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to\\n\\n[Verse 2]\\nNeighbors talk\\nThrough a half-closed door\\nCoffee cools\\nOn a cracked old floor\\nYour suitcase snaps\\nLike a camera flash\\nOne last quote\\nThen you cut to black\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to\\n\\n[Bridge]\\nIs there a line\\nWhere we rewind\\nOr just a feed\\nThat leaves us behind\\nTell me\\nWho gets\\nThe final view\\nWhen I stop trending\\nWith you\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to (yeah)",
    "custom": True,
    "instrumental": False,
    "audio_id": "0fa07665-6b8e-4a8b-8bd3-7e0cfcdada88",
    "samples_end": 102.16,
    "samples_start": 59.88
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

실행을 클릭하면 다음과 같은 결과를 얻을 수 있습니다:

```json theme={null}
{
  "success": true,
  "task_id": "12135a45-6384-4683-9bb1-64f19933915a",
  "trace_id": "683e559d-340e-4c72-8fae-e683442ac7e9",
  "data": [
    {
      "id": "9a0b680f-a9ea-4a36-8695-8ea777ab6ee7",
      "title": "Whistle in the Wind",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-053",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-054",
      "lyric": "[Verse 1]\nPhone lit up\nHeadline in my hand\nFeels made up\nStill says “you won’t understand”\nYour name\nMy name\nSide by side in the scroll\nCold black text\nOn a story I used to hold\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Verse 2]\nNeighbors talk\nThrough a half-closed door\nCoffee cools\nOn a cracked old floor\nYour suitcase snaps\nLike a camera flash\nOne last quote\nThen you cut to black\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Bridge]\nIs there a line\nWhere we rewind\nOr just a feed\nThat leaves us behind\nTell me\nWho gets\nThe final view\nWhen I stop trending\nWith you\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to (yeah)",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-31T14:34:45.043Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic with a hint of optimism,folk-pop,female vocals",
      "duration": 176.92
    },
    {
      "id": "66473dee-3aaf-43b2-80fd-76568b3abbb1",
      "title": "Whistle in the Wind",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-055",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-056",
      "lyric": "[Verse 1]\nPhone lit up\nHeadline in my hand\nFeels made up\nStill says “you won’t understand”\nYour name\nMy name\nSide by side in the scroll\nCold black text\nOn a story I used to hold\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Verse 2]\nNeighbors talk\nThrough a half-closed door\nCoffee cools\nOn a cracked old floor\nYour suitcase snaps\nLike a camera flash\nOne last quote\nThen you cut to black\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Bridge]\nIs there a line\nWhere we rewind\nOr just a feed\nThat leaves us behind\nTell me\nWho gets\nThe final view\nWhen I stop trending\nWith you\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to (yeah)",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-31T14:34:45.043Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic with a hint of optimism,folk-pop,female vocals",
      "duration": 177.48
    }
  ]
}
```

이로써 샘플링을 통한 노래 생성 작업이 완료되며, 결과는 위 내용과 유사합니다.

## Inspo 영감 창작 기능

Inspo 영감 창작 기능은 1\~4개의 완전한 참고 오디오를 바탕으로 새로운 음악을 생성할 수 있으며, 오디오를 드래그 앤 드롭하거나 업로드하여 영감 소스로 사용할 수 있습니다. API는 기존의 `inspo` action을 사용합니다. 클라이언트가 공개적으로 접근 가능한 오디오 URL을 제공하면 서비스가 참고 오디오 준비와 창작을 자동으로 완료하므로, 클라이언트가 가사, 스타일 또는 길이를 각각 읽어 요청을 조합할 필요가 없습니다. 이는 위의 구간 샘플링과도 다르고, 원곡 스타일을 복제하는 Cover와도 다릅니다. 사용할 때는 다음 매개변수를 입력해야 합니다:

* action: 내용은 `inspo`입니다.
* audio\_urls: 참고 오디오 URL 목록으로, 공개적으로 접근 가능한 오디오 주소를 1\~4개 제공해야 합니다.
* model: 사용하는 모델이며, `chirp-v6`를 권장합니다.
* prompt: 가사 또는 창작 프롬프트(선택 사항).

> 안내: 참고 오디오는 공개적으로 접근 가능한 오디오 파일이어야 합니다. 참고 오디오가 플랫폼 음원 라이브러리의 알려진 녹음과 완전히 일치하는 경우, Suno는 저작권 검증으로 인해 생성을 거부할 수 있으므로 자체 소유 오디오 또는 Suno가 생성한 오디오를 영감 소스로 사용하는 것을 권장합니다.

해당 Python 코드:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "inspo",
    "model": "chirp-v6",
    "audio_urls": [
        "https://cdn.acedata.cloud/uploads/a0bc051f-42c2-4a46-aeb4-582dcc884ad2"
    ],
    "prompt": "Rework these references as warm acoustic folk with soft vocals"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

아래에는 검증된 과거 응답 스냅샷을 보관합니다. 스냅샷은 당시의 `chirp-v5`를 사용했으며, 현재 요청 예시는 `chirp-v6`를 권장합니다. 반환 구조는 동일합니다:

```json theme={null}
{
  "success": true,
  "task_id": "725e6b41-78d0-4adf-856c-05e81098c029",
  "trace_id": "8c2f0b3e-2f6a-4738-8b1d-c58068ca3dab",
  "data": [
    {
      "id": "20ca5628-86e0-4c32-8ae4-9f0c481e45f3",
      "title": "Inspo Demo",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-057",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-06-18T13:01:53.910Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic, folk, warm",
      "duration": 36.92
    },
    {
      "id": "8744a796-9961-45af-868d-4f3bc1c44257",
      "title": "Inspo Demo",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-058",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-06-18T13:01:53.910Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic, folk, warm",
      "duration": 84.16
    }
  ]
}
```

이로써 영감 창작 작업이 완료되며, 반환 결과는 일반적인 노래 생성과 동일합니다.

## 비동기 콜백

Suno가 음악을 생성하는 데 걸리는 시간이 비교적 길며, 약 1\~2분이 필요합니다. API가 장시간 응답하지 않을 경우 HTTP 요청은 계속 연결 상태를 유지하게 되어 추가적인 시스템 리소스가 소모됩니다. 따라서 본 API는 비동기 콜백도 지원합니다.

전체 과정은 다음과 같습니다. 클라이언트가 요청을 시작할 때 추가로 `callback_url` 필드를 지정합니다. 클라이언트가 API 요청을 시작한 후 API는 즉시 현재 작업 ID를 나타내는 `task_id` 필드 정보를 포함한 결과를 반환합니다. 작업이 완료되면 생성된 음악 결과는 POST JSON 형식으로 클라이언트가 지정한 `callback_url`로 전송되며, 여기에도 `task_id` 필드가 포함되어 있어 ID를 통해 작업 결과를 연결할 수 있습니다.

아래 예시를 통해 구체적으로 어떻게 작업하는지 알아보겠습니다.

먼저, Webhook 콜백은 HTTP 요청을 수신할 수 있는 서비스이며, 개발자는 이를 직접 구축한 HTTP 서버의 URL로 교체해야 합니다. 여기서는 시연의 편의를 위해 공개 Webhook 예제 사이트 [https://webhook.site/](https://webhook.site/) 를 사용합니다. 해당 사이트를 열면 아래 그림과 같이 Webhook URL을 얻을 수 있습니다.

![](https://cdn.acedata.cloud/fwfqin.png)

이 URL을 복사하면 Webhook으로 사용할 수 있으며, 여기서의 예시는 [https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2](https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2) 입니다.

다음으로, `callback_url` 필드를 위 Webhook URL로 설정하고, 동시에 `prompt`를 입력할 수 있습니다. 아래 그림과 같습니다.

![](https://cdn.acedata.cloud/x8xql1.png)

실행을 클릭하면 아래와 같이 즉시 결과를 얻을 수 있습니다.

```
{
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60"
}
```

잠시 기다리면 [https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2](https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2) 에서 아래 그림과 같이 생성된 노래의 결과를 확인할 수 있습니다.

![](https://cdn.acedata.cloud/f9kosb.png)

내용은 다음과 같습니다.

```json theme={null}
{
  "success": true,
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60",
  "data": [
    {
      "id": "da4324e5-84b2-484b-b0e9-dd261381c594",
      "title": "Winter Whispers",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-059",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    },
    {
      "id": "b878a87b-a0db-4046-8ccd-ecd2fb3d4372",
      "title": "Winter Whispers",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-060",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-004",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    }
  ]
}
```

결과에 `task_id` 필드가 있는 것을 확인할 수 있으며, 다른 필드는 위와 유사합니다. 이 필드를 통해 작업 연결을 구현할 수 있습니다.

물론 스트리밍 호출을 통해서도 결과를 얻을 수 있습니다. 요청 헤더의 `accept` 값을 `application/x-ndjson`로 설정하기만 하면 됩니다. 아래에서는 예시 입력을 사용하여 시연합니다.

![](https://cdn.acedata.cloud/vgffvk.png)

대기 과정에서 다음과 같은 출력을 얻을 수 있습니다.

```json theme={null}
{"success":true,"task_id":"1af4b454-ce84-4512-a0a2-de3f8574ecd8","data":[{"id":"1f610752-f426-4fd5-89a8-ba2ad0370881","title":"Snowflakes and Mistletoe","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"pending","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar"},{"id":"d1a3109d-799b-401e-b032-4b501bcf26f3","title":"Snowflakes and Mistletoe","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"pending","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar"}]}
{"success":true,"task_id":"1af4b454-ce84-4512-a0a2-de3f8574ecd8","trace_id":"4440342a-41c4-4140-8bb1-3537a598ca2e","data":[{"id":"1f610752-f426-4fd5-89a8-ba2ad0370881","title":"Snowflakes and Mistletoe","image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-073","image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-074","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"succeeded","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar","duration":129.92},{"id":"d1a3109d-799b-401e-b032-4b501bcf26f3","title":"Snowflakes and Mistletoe","image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-075","image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-076","lyric":"[Verse]\nLights are tangled on the tree again\nThe cat’s knocked over the wreath\nCookies burning in the oven too\nBut I’m still grinning through my teeth\n[Prechorus]\nSnow is falling like glitter in the sky\nI’ve got a feeling this year’s gonna fly\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe\n[Verse 2]\nGrandma’s singing a little off-key\nThe kids are laughing too loud\nThe dog’s stolen a turkey leg\nChaos is a Christmas crowd\n[Prechorus]\nBut the fire’s crackling\nWarm and bright\nAnd my heart’s a candle tonight\n[Chorus]\nSnowflakes and mistletoe\nEverywhere I go\nI know\nLove is the gift\nThe glow\nSnowflakes and mistletoe","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"succeeded","prompt":"A song for Christmas","style":"uplifting, orchestral with bells and acoustic guitar","duration":127.16}]}
```

스트리밍 응답은 동일한 `task_id`에 대해 처리 중 상태와 최종 결과를 순차적으로 푸시합니다. 위에서는 최초 및 최종 상태의 실제 응답 두 개만 유지하고, 반복되는 중간 업데이트는 생략했습니다.

## 오류 처리

오류가 발생하면 다음과 유사한 오류 정보를 받게 됩니다:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "Song Description contained artist name: eminem"
  },
  "trace_id": "9bb7c2f4-3b7b-4965-b50a-f663874b1b6f",
  "task_id": "9bb3a2a6-c438-436d-a9f3-fa466abc077c"
}
```

아래는 HTTP Status Code, `error.code`, `error.message`의 목록입니다:

> 참고: 서로 다른 업스트림 계정의 한도와 오류 문구에는 차이가 있을 수 있습니다. 일반적으로 `chirp-v3-5`/`chirp-v4`의 `style` 제한은 더 낮으며(200), `chirp-v4-5` 이상은 보통 최대 1000까지 지원합니다. 이전 업스트림에 해당할 경우 `Tags too long.` 또는 `style must be less than or equal 120` 등의 호환 문구가 나타날 수 있습니다.
> \| 상태 코드 | `error.code`  | `error.message`                                                 |
> \| ----------- | ------------- | --------------------------------------------------------------- |
> \| 400         | `bad_request` | `노래 ID가 존재하지 않거나 오프라인 처리되었습니다.`             |
> \| 400         | `bad_request` | `프롬프트가 너무 깁니다.`                                       |
> \| 400         | `bad_request` | `태그가 너무 깁니다.`                                           |
> \| 400         | `bad_request` | `업로드된 오디오가 기존 예술 작품과 일치합니다.`                |
> \| 400         | `bad_request` | `instrumental은 불리언이어야 합니다`                            |
> \| 400         | `bad_request` | `제목이 너무 깁니다.`                                           |
> \| 400         | `bad_request` | `주제가 너무 깁니다.`                                           |
> \| 400         | `bad_request` | `style은 120 이하이어야 합니다`                                 |
> \| 400         | `bad_request` | `custom은 불리언이어야 합니다`                                  |
> \| 400         | `bad_request` | `오디오를 연장할 때 audio_id가 필요합니다`                      |
> \| 400         | `bad_request` | `오디오를 연장할 때 continue_at이 필요합니다`                   |
> \| 400         | `bad_request` | `continue_at은 0보다 큰 숫자여야 합니다`                        |
> \| 400         | `bad_request` | `오디오를 연장하고 instrumental이 false일 때 lyric이 필요합니다` |
> \| 400         | `bad_request` | `오디오를 생성할 때 prompt가 필요합니다`                        |
> \| 400         | `bad_request` | `사용자 지정 오디오를 생성할 때 lyric이 필요합니다`             |
> \| 403         | `forbidden`   | `프롬프트 형식이 잘못되었을 가능성이 높습니다`                  |
> \| 403         | `forbidden`   | `프롬프트에 저작권이 있을 가능성이 높습니다`                    |
> \| 403         | `forbidden`   | `프롬프트에 부적절한 자료가 포함되어 있습니다`                  |
> \| 403         | `forbidden`   | `노래 설명이 검토 대상으로 표시되었습니다`                      |
> \| 403         | `forbidden`   | `노래 설명에 아티스트 이름이 포함되어 있습니다`                 |
> \| 403         | `forbidden`   | `태그에 아티스트 이름이 포함되어 있습니다`                      |
> \| 403         | `forbidden`   | `가사에 저작권이 있는 자료가 포함되어 있습니다`                 |
> \| 403         | `forbidden`   | `노래 설명에 프로듀서 태그가 포함되어 있습니다`                 |
> \| 403         | `forbidden`   | `일반 OpenAI 오류`                                              |
> \| 403         | `forbidden`   | `프롬프트가 검토 대상으로 표시되었습니다`                       |
> \| 500         | `api_error`   | `노래 설명으로부터 가사를 생성할 수 없습니다`                   |
> \| 500         | `api_error`   | `알 수 없는 오류로 작업에 실패했습니다`                         |
> \| 500         | `api_error`   | `시스템에 사용 가능한 워커가 없습니다`                          |
> \| 500         | `api_error`   | `서비스가 유지보수 중이며 생성이 일시 중지되었습니다`           |
> \| 504         | `timeout`     | `오디오 생성 대기 중 시간 초과`                                 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.