음악 기능을 구축할 때, 가장 먼저 유용한 기본 요소(primitive)는 종종 "처음부터 전체 곡을 생성하는 것"이 아닙니다. 그것은 바로: 기존의 참조 트랙(reference track)을 가져와서, 안전하게 업로드하고, 필요한 메타데이터(metadata)를 추출한 다음, 워크플로우의 다음 단계에서 사용할 수 있도록 반환된 곡 ID(song ID)를 유지하는 것입니다.

이 가이드는 Ace Data Cloud의 Suno Upload Reference Audio API에 대해 설명합니다. 이 API는 의도적으로 작게 설계되었습니다: 공개적으로 접근 가능한 MP3 URL을 보내고, 업로드된 오디오 레코드(audio record)를 수신하며, 나중에 2차 생성을 위해 반환된 audio_id를 사용합니다.

수행할 수 있는 작업

업로드 엔드포인트(endpoint)는 다음과 같습니다:

Base URL: https://api.acedata.cloud
Endpoint: POST /suno/upload
Headers:
...

요청 본문(request body)에는 하나의 입력 파라미터(input parameter)가 있습니다:

{
  "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3"
}

중요한 제약 사항은 audio_url이 반드시 공개적으로 접근 가능한 CDN 주소여야 하며 .mp3 접미사를 지원해야 한다는 점입니다. 즉, 이 엔드포인트는 귀하의 앱이 이미 API가 가져올 수 있는 어딘가에 참조 오디오를 배치한 후에 사용하는 것이 가장 좋습니다.

응답은 정규화된 오디오 객체(audio object)를 제공합니다. 핵심 필드는 업로드 후의 곡 ID인 data.audio_id입니다. 응답에는 lyric(가사), style(스타일), image_url(이미지 URL), image_large_url(대형 이미지 URL), audio_url(오디오 URL), title(제목), duration(재생 시간)과 같이 추출되거나 생성된 컨텍스트(context)가 포함될 수 있습니다.

1단계: 업로드 요청하기

다음은 통합 형태의 전체 cURL 호출 예시입니다:

curl -X POST 'https://api.acedata.cloud/suno/upload' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
...

실제 애플리케이션에서는 데모 URL을 귀하의 자체 스토리지 또는 CDN에서 가져온 직접적인 MP3 URL로 교체하십시오. API를 호출하기 전에 저는 세 가지 사항을 검증할 것입니다:

1. 사용자 인증 없이도 URL에 접근 가능해야 합니다.
2. 파일은 웹 플레이어가 임베드된 웹 페이지가 아닌, MP3 URL이어야 합니다.
3. 백엔드에서 요청을 보내기 전에 원본 소스 URL을 저장해야 합니다.

세 번째 사항이 중요한 이유는, 반환된 데이터는 플랫폼이 생성한 결과물을 알려주는 반면, 소스 URL은 사용자가 원래 제공한 데이터가 무엇인지 알려주기 때문입니다.

2단계: 응답을 워크플로우 객체로 읽기

성공적인 응답은 일반적으로 다음과 같은 형태를 가집니다:

{
  "success": true,
  "task_id": "058f8450-3df4-4f8b-8b64-ebc2e59ed3bc",
...

제가 영구 저장할 필드들은 다음과 같습니다:

• 업로드 요청 추적을 위한 task_id
• 추후 음악 생성 또는 확장 (extension) 흐름을 위한 data.audio_id
• 재생을 위한 data.audio_url
• UI 표시 및 검증을 위한 data.duration
• 제품에서 사용자가 추출된 음악적 맥락을 검토하거나 편집할 수 있게 하는 경우 data.lyric 및 data.style

업로드 응답을 "에셋 등록 (asset registration)" 단계로 취급하십시오. 이 단계가 끝나면, 앱은 이후의 음악 생성 작업에 전달할 수 있는 ID를 보유하게 됩니다.

3단계: 보조 생성 작업과 연결하기

문서에 따르면, 노래 ID를 확보한 후에는 Suno Audios Generation API를 사용하여 커스텀 곡을 생성할 수 있습니다. 구체적인 전달 방식은 action을 upload_extend로 전달하고, 반환된 audio_id를 참조 곡 ID로 사용하는 것입니다.

깔끔한 백엔드 추상화는 다음과 같은 모습일 수 있습니다:

uploadReferenceAudio({ audio_url }) -> { task_id, audio_id, lyric, style, audio_url, duration }

그러면 다음 워크플로우 단계에서는 원본 파일이 어디에서 왔는지 알 필요 없이 audio_id를 받아들일 수 있습니다.

이러한 분리는 제품 코드 작성에 큰 도움이 됩니다. 참조 오디오 업로드, 추출된 맥락 검토, 그리고 파생 곡 생성은 서로 다른 사용자 액션입니다. 이들을 분리해 두면 인터페이스를 디버깅하기 쉬워지고 재시도(retry)하기도 용이해집니다.

4단계: 제약 사항을 고려한 사용자 흐름 설계

API가 공개된 MP3 URL을 요구하기 때문에, 사용자 대상 흐름에서는 해당 제약 사항을 명확히 인지시켜야 합니다. 실질적인 흐름은 다음과 같습니다:

1. 사용자가 앱에 MP3를 업로드합니다.
2. 백엔드(Backend)가 이를 CDN 또는 오브젝트 스토리지 버킷(Object storage bucket)에 저장합니다.
3. 백엔드가 공개된 audio_url과 함께 POST /suno/upload를 호출합니다.
4. 앱이 반환된 제목(Title), 재생 시간(Duration), 커버 이미지(Cover image), 가사(Lyric), 스타일(Style)을 표시합니다.
5. 사용자가 audio_id를 사용하여 2차 생성 단계(Secondary creation step)를 진행할지 여부를 확인합니다.

업로드가 실패할 경우, 사용자가 처음부터 다시 시작할 필요가 없도록 원래의 사용자 파일과 소스 URL을 유지하십시오. 업로드는 성공했지만 이후 생성 단계가 실패하더라도, 여전히 audio_id를 보유하고 있으므로 다운스트림(Downstream) 단계를 재시도할 수 있습니다.

작지만 유용한 프리미티브 (Primitive)

이 엔드포인트(Endpoint)는 의도적으로 범위를 좁게 설정하였으며, 바로 그 점이 유용함을 만듭니다. 이 엔드포인트는 단 한 번의 요청으로 전체 음악 워크플로우 (Music workflow)를 모델링하도록 요구하지 않습니다. 대신 기존 MP3 참조(Reference)로부터 나중에 사용할 수 있는 audio_id로 이어지는 하나의 신뢰할 수 있는 가교(Bridge)를 제공합니다.

개발자(Builders)에게 이는 좋은 경계(Boundary)입니다. 참조를 등록하기 위한 하나의 API 호출, 향후 작업을 위해 저장된 하나의 ID, 그리고 사용자의 오디오에서 무엇이 파악되었는지 사용자에게 보여줄 수 있는 충분한 메타데이터(Metadata)를 제공하기 때문입니다.

전체 필드 참조(Field reference)는 Suno Upload API 문서에서 확인할 수 있습니다: https://platform.acedata.cloud/documents/suno-upload-integration