소스 오디오 업로드 API

2026-09-18 업데이트 · Suno-API 팀

인터페이스 설명

소스 오디오 업로드는 로컬 또는 원격 오디오를 이후의 커버·연장·구간 교체·스템 분리 등에 사용할 수 있는 소스 clip으로 업로드합니다.

엔드포인트: POST /api/music/upload-source

과금: 무료. 이 엔드포인트는 소스 오디오만 업로드하며 생성 작업을 시작하지 않습니다.

권장 사용법: '2단계 커버'의 1단계입니다. 먼저 이 엔드포인트로 오디오를 업로드하고(무료이며 실패하면 언제든 다시 시도할 수 있습니다) 반환된 clip_id를 저장하세요. 업로드가 성공했는지(status가 완료 상태) 확인한 뒤 소스 clip 기반 커버 API를 호출해 커버를 시작합니다. 이 단계의 요청 본문은 수백 바이트에 불과하므로 오디오가 너무 커서 전송 중 잘리는 일이 없습니다. 한 번에 처리하는 업로드 후 커버 API와 비교하면 이렇게 나누는 방식은 오디오가 크거나 네트워크가 불안정하거나 같은 소재를 여러 번 재사용할 때(연장 / 구간 교체 / 스템 분리) 더 안정적입니다.

대용량 파일 업로드 팁

업로드가 끝나면 반드시 응답의 status가 완료 상태인지 확인하고 clip_id를 저장한 뒤 2단계로 넘어가세요. 업로드가 실패해도 요금이 청구되지 않고 생성 작업도 만들어지지 않으므로 그대로 다시 시도하면 됩니다.

업로드 전에 file_url 확인

file_url은 브라우저가 아니라 플랫폼 서버가 직접 HTTP로 다운로드합니다. 브라우저에서 열리는 URL이라도 운영 서버에서 접근 가능한 것은 아닙니다.

로컬 파일은 file 필드를 사용하는 multipart 업로드를 권장합니다. ByteDance 등의 임시 서명 URL은 공개 접근이 가능하고 요청 시점에 아직 유효한 경우가 아니면 file_url로 사용하지 마세요.

업로드 요청 전에 공용 서버에서 다음을 실행하세요.

curl -L --max-time 30 -D - -o /dev/null "https://example.com/source.mp3"

GET 요청은 HTTP 200으로 끝나야 하고, audio MIME을 반환하며, 내용이 비어 있지 않아야 합니다. 로그인 페이지, HTML 응답, 401, 403, 404, 410은 서버에서 사용할 수 없습니다.

file_url download failed: HTTP 404는 보통 서명 만료, 파일 삭제 또는 URL 매개변수 누락을 의미합니다.

업로드는 무료입니다. file_url 다운로드가 실패하면 clip_id, 곡 작업, 생성 호출이 만들어지지 않고 요금도 청구되지 않으므로 환불이 필요하지 않습니다.

요청 파라미터

Headers

JSON 요청:

multipart 요청에서는 Content-Type을 직접 지정하지 마세요. 클라이언트가 자동으로 생성합니다.

바디 파라미터

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"

import requests

with open("source.mp3", "rb") as audio:
    response = requests.post(
        "https://www.suno-api.io/api/music/upload-source",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "file_name": "source.mp3",
            "upload_type": "file_upload",
            "model": "suno-v6",
        },
        files={"file": ("source.mp3", audio, "audio/mpeg")},
        timeout=300,
    )

response.raise_for_status()
print(response.json())

응답 결과

{
  "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": {}
}