강화 업로드 API

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

인터페이스 설명

강화 업로드는 로컬 오디오 파일을 제출하면 시스템이 백그라운드에서 강화 처리를 수행해 재생 가능한 완성 곡을 만들어 내는 기능입니다. 제출하면 작업 정보가 즉시 반환되고, 클라이언트는 조회 엔드포인트로 진행 상황을 폴링합니다.

제출 엔드포인트: POST /api/music/enhanced-upload

단일 작업 조회: GET /api/music/enhanced-upload/:id

작업 취소: POST /api/music/enhanced-upload/:id/cancel

목록 조회: GET /api/music/enhanced-upload

과금: 1회 10위안. suno-enhanced-upload 고정 가격으로 미리 차감됩니다. 작업이 실패하거나 허용된 단계에서 취소하면 미리 차감한 금액이 자동으로 환급됩니다. 실제 청구 금액은 현재 백오피스 가격 설정을 따릅니다.

호출 흐름

POST /api/music/enhanced-upload를 호출해 오디오 파일을 업로드합니다.
반환된 task_id를 저장합니다.
GET /api/music/enhanced-upload/:id를 호출해 진행 상황과 결과를 조회합니다.
Suno의 최종 렌더링이 끝나면 서비스는 해당 작업에 연결된 Suno 계정으로 Studio 인가 다운로드 엔드포인트를 호출하고, MP3를 CN2 미디어 서비스에 기록합니다.
CN2 자산 준비가 성공해야만 작업이 completed가 되며, 그때 응답의 audio_url에서 CDN 오디오 주소를 가져옵니다.

/api/forbidden은 Suno Studio 메타데이터에 나타날 수 있는 자리표시자 주소이며, 재생하거나 내려받을 수 있는 리소스가 아닙니다. 고객에게 반환되지도 않고 완료 판정의 근거로 쓰이지도 않습니다. 렌더링은 끝났는데 CN2가 아직 준비 중이면 엔드포인트는 계속 processing을 반환하고 audio_url을 반환하지 않습니다. 클라이언트는 폴링을 계속하고 빈 주소를 실패로 보지 마세요.

강화 업로드 제출

Headers

파라미터	타입	필수	설명
Authorization	string	예	Bearer YOUR_API_KEY
Content-Type	string	아니오	multipart 요청에서는 직접 지정하지 말고 클라이언트가 생성하게 하세요

Form 파라미터

파라미터	타입	필수	기본값	설명
file	file	예	-	로컬 오디오 파일, 최대 80 MB
title	string	아니오	확장자를 뺀 파일 이름	곡 제목

요청 예시

아래 예시는 프로덕션 검증 때와 같은 호출 방식이지만 API Key는 자리표시자로 바꾼 것입니다.

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

응답 결과

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

단일 작업 조회

요청 예시

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

처리 중 응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

완료 응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

작업 취소

취소할 수 있는 것은 작업과 백엔드 워크플로가 모두 queued 단계에 있을 때뿐입니다. 작업이 leasing, running, processing에 들어가거나 완료된 뒤에는 취소할 수 없습니다.

요청 예시

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

응답 결과

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

작업이 이미 처리를 시작했다면 엔드포인트는 다음을 반환합니다.

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

작업 목록 조회

목록 엔드포인트는 현재 API Key가 속한 사용자의 강화 업로드 작업만 반환하며, 일반 생성·커버·이어쓰기 작업은 섞이지 않습니다.

Query 파라미터

파라미터	타입	필수	기본값	설명
p	number	아니오	1	페이지 번호
page_size	number	아니오	시스템 기본값	페이지당 개수, 최대 100

요청 예시

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

응답 결과

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

반환 필드 설명

필드	타입	설명
task_id	number	강화 업로드 작업 ID. 이후 조회와 취소에 이 값을 사용합니다
song_id	string	처리 중에는 `pending:enhanced-upload:*`, 완료 후에는 실제 곡 ID
client_request_id	string	클라이언트 요청 추적 ID
status	string	작업 상태. `queued`, `processing`, `completed`, `failed`, `cancelled` 등
type	string	항상 `enhanced_upload`
audio_url	string	완료 후의 오디오 주소
duration	number	오디오 길이(초)
progress.stage	string	현재 처리 단계
progress.percent	number	진행률(%)
progress.label	string	사용자에게 표시하는 진행 문구
pre_consumed_quota	number	이번에 미리 차감한 한도
billing_source	string	차감 출처. 예: `wallet`
error_message	string	실패 사유

주의 사항

현재 이 엔드포인트는 multipart 파일 업로드만 지원하며 JSON file_url이나 file_base64는 지원하지 않습니다.
업로드 파일은 최대 80 MB입니다.
제출 엔드포인트는 비동기이며, queued가 반환되는 것은 작업이 대기열에 들어갔다는 뜻일 뿐 오디오가 완성됐다는 뜻이 아닙니다.
취소는 아직 처리가 시작되지 않은 작업에만 적용됩니다. 처리 단계에 들어가면 플랫폼 계정 워크플로는 중단되지 않습니다.
클라이언트 코드에 실제 API Key를 노출하지 마세요.

강화 업로드 완료 후 커버 시작

강화 업로드가 완료되면 그 결과를 소스 clip으로 삼아 POST /api/music/generate-from-source를 호출해 커버를 시작할 수 있습니다.

주의: 커버는 동기 엔드포인트이며 응답이 돌아온 시점에야 주문이 접수됩니다. 실측 기준 최대 약 230초까지 기다릴 수 있습니다. 클라이언트 타임아웃을 300초 이상으로 설정하고, 타임아웃 후 바로 재시도하지 마세요. 자세한 내용은 새 API 개요의 "대기 시간과 타임아웃 설정"을 참고하세요.

먼저 GET /api/music/enhanced-upload/:id를 폴링해 task.status가 completed가 될 때까지 기다립니다. 그때:

task.song_id는 실제 곡 ID이며 커버 엔드포인트가 필요로 하는 sourceClipId이기도 합니다.
task.audio_url은 sourceAudioUrl로 함께 넘기는 것을 권장합니다. 소스 clip과 실행 계정이 다를 때 서버가 처리하기 쉬워집니다.
task.task_id는 강화 업로드 작업 ID일 뿐이며 sourceClipId로 쓸 수 없습니다.
pending:enhanced-upload:*는 처리 단계의 자리표시자 ID이며 커버에 쓸 수 없습니다.

커버를 시작할 때는 강화 업로드와 같은 API Key를 사용하고, 아래 필드 대응에 따라 요청을 구성하세요.

커버 요청 필드	값의 출처
`sourceClipId`	강화 업로드 완료 결과의 `task.song_id`
`sourceAudioUrl`	강화 업로드 완료 결과의 `task.audio_url`
`sourceTitle`	강화 업로드 완료 결과의 `task.title`

나머지 가사, 스타일, 제목, 모델 등 파라미터는 소스 clip 기반 커버 API에 따라 채웁니다. 커버 엔드포인트가 새로운 clips[].song_id를 반환하면 POST /api/music/query로 생성 상태와 최종 오디오를 조회하세요.

다음업로드 후 커버 API

API 키 발급

가입 후 콘솔에서 API 키를 만들 수 있습니다. 1회 0.6위안으로 2곡이 생성되고, 다운로드는 횟수 제한이 없으며 휴대폰 번호는 필요하지 않습니다.

API 키 받기 개요로 돌아가기