소스 오디오 업로드 API
인터페이스 설명
소스 오디오 업로드는 로컬 또는 원격 오디오를 이후의 커버·연장·구간 교체·스템 분리 등에 사용할 수 있는 소스 clip으로 업로드합니다.
엔드포인트: POST /api/music/upload-source
과금: 무료. 이 엔드포인트는 소스 오디오만 업로드하며 생성 작업을 시작하지 않습니다.
권장 사용법: '2단계 커버'의 1단계입니다. 먼저 이 엔드포인트로 오디오를 업로드하고(무료이며 실패하면 언제든 다시 시도할 수 있습니다) 반환된
clip_id를 저장하세요. 업로드가 성공했는지(status가 완료 상태) 확인한 뒤 소스 clip 기반 커버 API를 호출해 커버를 시작합니다. 이 단계의 요청 본문은 수백 바이트에 불과하므로 오디오가 너무 커서 전송 중 잘리는 일이 없습니다. 한 번에 처리하는 업로드 후 커버 API와 비교하면 이렇게 나누는 방식은 오디오가 크거나 네트워크가 불안정하거나 같은 소재를 여러 번 재사용할 때(연장 / 구간 교체 / 스템 분리) 더 안정적입니다.
대용량 파일 업로드 팁
| 상황 | 권장 방법 |
|---|---|
| 오디오가 이미 공개 상태(https 직링크 있음) | file_url 사용: 요청 본문이 수백 바이트로 가장 안정적 |
| 로컬 파일(Node / Python / 데스크톱) | multipart 업로드(-F "file=@source.mp3")를 사용하고 Content-Type을 직접 설정하지 마세요 |
| JSON + base64만 가능 | Content-Length는 바이트 수(Buffer.byteLength)여야 합니다. 그렇지 않으면 요청 본문이 잘릴 수 있습니다 |
업로드가 끝나면 반드시 응답의 status가 완료 상태인지 확인하고 clip_id를 저장한 뒤 2단계로 넘어가세요.
업로드가 실패해도 요금이 청구되지 않고 생성 작업도 만들어지지 않으므로 그대로 다시 시도하면 됩니다.
요청 파라미터
Headers
JSON 요청:
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| Authorization | string | 예 | Bearer YOUR_API_KEY |
| Content-Type | string | 예 | application/json |
multipart 요청에서는 Content-Type을 직접 지정하지 마세요. 클라이언트가 자동으로 생성합니다.
바디 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| model | string | 아니오 | suno-v6 | 대고객 모델명: suno-v6, suno-v6-wild, suno-v6-mini |
| file_url | string | 아니오 | - | 원격 오디오 URL |
| file_base64 | string | 아니오 | - | Base64 오디오 |
| file_name | string | 아니오 | - | 파일 이름 |
| upload_type | string | 아니오 | file_upload | 업로드 유형 |
JSON 요청 예시
curl -X POST https://www.suno-api.io/api/music/upload-source \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"file_url": "https://example.com/source.mp3",
"file_name": "source.mp3",
"upload_type": "file_upload"
}'
multipart 요청 예시
curl -X POST https://www.suno-api.io/api/music/upload-source \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@source.mp3" \
-F "file_name=source.mp3" \
-F "upload_type=file_upload" \
-F "model=suno-v6"
응답 결과
{
"clip_id": "uploaded_clip_id",
"status": "complete",
"title": "source.mp3",
"image_url": "https://...",
"audio_url": "https://...",
"display_tags": "pop, vocal",
"inferred_description": "uploaded source audio",
"clip_metadata": {}
}