Suno API 문서 개요

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

이메일로 가입하면 API 키를 만들 수 있습니다. 생성은 1회 0.6위안에 2곡을 반환하며 MP3/WAV 다운로드, 커버, 이어 만들기, 스템 분리, 보이스 클론을 지원합니다. 기본 URL은 https://www.suno-api.io입니다.

이 페이지에서는 현재 사용할 수 있는 모델, 모든 생성·편집 인터페이스, 과금 방식, 권장 학습 순서를 설명합니다. 처음 연동하는 경우 위에서부터 차례대로 읽어 주세요. 401/403/429 대응 안내도 여기에 있습니다.

빠른 답변

API 키는 어떻게 발급받나요? 이메일로 가입한 뒤 콘솔 → 토큰 관리에서 새 토큰을 만들면 됩니다. 휴대폰 번호도, 카드 등록도 필요하지 않습니다.

한 번에 얼마인가요? 생성은 1회 0.6위안에 2곡을 반환합니다. 상태 조회, WAV, 타임스탬프 가사, 프롬프트 제안 같은 인터페이스는 추가 요금이 없습니다.

어떤 모델을 지원하나요? suno-v6(기본), suno-v6-wild, suno-v6-mini입니다. v5.5 및 그 이전 일반 생성 모델은 종료되었고, 기존 작업물에는 영향이 없습니다.

기본 URL은 무엇인가요? https://www.suno-api.io이며, 요청 헤더에 Authorization: Bearer YOUR_API_KEY를 넣습니다.

현재 사용할 수 있는 모델

일반 곡 생성에서 고객이 지정할 수 있는 모델은 suno-v6, suno-v6-wild, suno-v6-mini 세 가지이며, model을 생략하면 suno-v6가 사용됩니다.

일반 모델 suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5, suno-v5-5는 종료되었습니다. 과거 작업을 조회하면 예전 모델명이 남아 있을 수 있지만 이는 이력 데이터일 뿐이며, 그 모델을 새 요청에 쓸 수 있다는 뜻이 아닙니다. 예외는 스템 분리이며 자세한 내용은 스템(보컬·반주 분리) API를 참고하세요.

인증 방식

공개 API 키 인터페이스는 모두 같은 헤더를 사용합니다.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

기본 URL:

https://www.suno-api.io

파라미터 공통 규칙

• 요청 본문의 number는 JSON 숫자로 보내야 하며 퍼센트 문자열은 안 됩니다. 강도 50%는 0.5로 쓰고, 50이나 50%로 쓰지 않습니다.
• boolean은 true 또는 false를 보내야 합니다. true, false, 0, 1 같은 대체 값을 쓰지 마세요.
• "아니오"로 표시된 필드는 아예 보내지 않아도 됩니다. 의미가 불확실한 파라미터는 생략하고 서비스 기본 동작에 맡기세요. 보내지 않았다는 뜻으로 빈 문자열, null, 0을 쓰지 마세요. 일부 숫자 필드에서 0은 유효한 값이기 때문입니다.
• 필드 이름은 철자를 구분합니다. 각 인터페이스 문서에 권장 필드와 호환 필드를 적어 두었습니다. 새로 연동할 때는 파라미터 표에 있는 그대로 보내세요. snake_case와 camelCase를 모두 지원한다고 적혀 있더라도 두 가지를 동시에 보내지 마세요.
• _s 또는 Seconds로 끝나는 시간 필드의 단위는 초이며 소수도 사용할 수 있습니다. Unix 타임스탬프는 초인지 밀리초인지 따로 표기합니다.
• pending:으로 시작하는 ID는 플랫폼의 임시 ID이며 실제 곡 ID가 아닙니다. 임시 ID를 지원한다고 명시한 인터페이스에서만 사용하고, 그 외에는 실제 song_id가 반환될 때까지 기다리세요.

텍스트 필드 길이 제한

제한을 넘기면 곧바로 HTTP 400을 반환합니다. 생성이 시작되지 않고, 사전 차감도 없으며, 작업 레코드도 만들어지지 않습니다. 계산은 Unicode 문자 기준(한글·한자 1자 = 1문자)이고 앞뒤 공백도 포함됩니다.

초과 시 message에 대상 필드명과 실측 글자 수가 그대로 나오므로 그 두 숫자에 맞춰 줄이면 됩니다.

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

적용 인터페이스: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

유일한 예외는 POST /api/music/sounds의 description(효과음 설명)이며 제한은 100자입니다. 효과음은 플랫폼의 더 짧은 제한을 따릅니다.

비동기 생성과 오디오 주소

음악 생성 인터페이스는 기본적으로 비동기로 동작합니다. 첫 응답의 status가 pending, submitted, processing일 때 audio_url, video_url, cover_url이 비어 있는 것은 정상이며 실패를 뜻하지 않습니다. 실제 song_id(또는 반환된 client_request_id)를 저장하고 해당 조회 인터페이스로 폴링하세요. 오디오 주소를 읽거나 내려받는 것은 상태가 완료된 뒤입니다.

⚠️ 오디오 주소는 7일 후 만료됩니다. 기한 안에 옮겨 두세요

audio_url, wav_url, video_url 및 각 다운로드 인터페이스가 반환하는 주소는 플랫폼 오브젝트 스토리지에서 제공되며 기본 7일 후 만료됩니다(파일이 회수되고 이전 주소는 404/다운로드 불가).

• 주소를 받은 뒤 7일 안에 자체 저장소로 옮기세요(자체 오브젝트 스토리지, CDN, 서버 디스크 모두 가능). 저희 주소를 장기 링크로 쓰지 마세요.
• 만료되어도 곡을 다시 생성할 필요가 없고 추가 비용도 없습니다. 곡 조회 API(또는 미디어 다운로드 API)를 다시 호출하면 해당 곡의 새로운 유효 주소를 받습니다.

대기 시간과 타임아웃 설정

생성 인터페이스는 동기 인터페이스입니다. 응답이 돌아온 시점에야 주문이 접수되어 플랫폼에 생성이 넘어갑니다. 그전까지 서버는 계정 배정과 필요한 안전 검증을 수행하며, 중간 응답은 전혀 없고 다른 인터페이스로도 이 주문을 볼 수 없습니다. 따라서 "생성되었는지"를 판단할 수 있는 유일한 근거는 응답 자체이며, 기다리는 동안 관찰되는 어떤 현상도 근거가 되지 않습니다.

실측 대기 시간(2026-09-18 ~ 2026-09-20, 프로덕션 /api/music/create 계열)

• 약 10%의 요청은 30초 이상 걸리고 약 1%는 1~2분 걸립니다. 오래 걸리는 요청은 대개 이번에 안전 검증을 한 번 통과해야 했던 경우입니다.
• 요청 필드, 응답 구조, 오류 코드, 과금 방식은 모두 그대로이므로 기존 연동은 클라이언트 타임아웃만 조정하면 되고 다른 코드는 고칠 필요가 없습니다.

연동 요구 사항

1. 클라이언트 타임아웃을 300초 이상으로 설정하세요. 기본값이 30초·60초·120초인 클라이언트는 대기 중에 스스로 연결을 끊습니다.
2. 응답이 없다고 해서 생성되지 않은 것이 아닙니다. 연결이 끊기거나 타임아웃되어도 주문은 이미 접수되어 생성 중일 수 있습니다.
3. 타임아웃 후 즉시 재시도하지 마세요. 같은 요청을 다시 보내면 새 주문이 만들어져 다시 과금됩니다.
4. 연결이 끊겼다면 잠시 후 GET /api/music/songs를 최신순으로 확인하세요. 접수된 주문은 정상적으로 목록에 나타납니다. 정말 없다는 것을 확인한 뒤 다시 보내세요.
5. 장애를 신고할 때는 응답 헤더의 X-Oneapi-Request-Id를 함께 주세요. 해당 요청 한 건을 바로 찾을 수 있습니다.

긴 연결을 유지하기 어렵다면 접수 영수증 모드를 쓰세요. POST /api/music/create와 POST /api/music/create/custom은 선택적 접수 영수증을 지원합니다. 본문에 "accept_mode": "async"(또는 헤더 X-Accept-Mode: async)를 넣으면 곧바로 202와 접수 번호가 반환되고 생성은 백그라운드에서 계속됩니다. 진행 상황은 GET /api/music/requests/{request_id}로 확인합니다. 타임아웃이 수십 초뿐인 클라이언트도 "생성되지 않았다"고 잘못 판단하지 않고, 재시도로 인한 이중 과금도 피할 수 있습니다. 자세한 내용은 심플 모드 생성 API의 "접수 영수증 모드"를 참고하세요.

참고: python requests는 timeout=300, urllib는 urlopen(..., timeout=300), Node는 req.setTimeout(300000), curl은 --max-time 300을 사용합니다.

권장 인터페이스 목록

위의 /api/voice/clone/*와 /api/music/generate-with-voice는 초기 보이스 클론 경로이며 신규 연동에 권장하지 않습니다. 【권장】보이스 프로필 API를 사용하세요.

고급 파라미터: Max Mode와 Variety

생성 인터페이스는 다음 두 선택 파라미터를 지원합니다(보내지 않으면 기존 동작과 가격이 그대로 유지됩니다).

지원 인터페이스: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• max_mode 2배 가격 예시: 기본 1회 0.6위안인 인터페이스는 켜면 1.2위안이 됩니다. 지정 보이스로 생성은 기본 1회 1.2위안이며 켜면 2.4위안입니다. 【권장】보이스 프로필 API의 보이스 커버도 1회 1.2위안(켜면 2.4위안)입니다.
• variety는 suno-v6 계열(suno-v6, suno-v6-wild, suno-v6-mini)에만 적용되며, 다른 모델에 보내면 400을 반환합니다.
• 효과음 생성, 스템 분리, 연결, WAV, Studio 편집 계열(자르기, 구간 삭제, 페이드, 역재생, 속도 변경 등)에는 이 두 파라미터가 없습니다. 명시적으로 보내면 400을 반환해 "보냈는데 적용되지 않는" 상황을 만들지 않습니다.
• variety는 0-4 정수 원값이며 style_weight, weirdness_constraint(0-1 소수)와 단위가 다릅니다.

공통 곡 응답 필드

생성, 커버, 이어 만들기, 분리, 조회 인터페이스는 보통 곡 배열을 반환하며 자주 쓰는 필드는 다음과 같습니다.

연동 4단계(최소 예시)

새로 연동할 때는 이 4단계만 거치면 첫 곡을 받을 수 있습니다. 각 단계의 전체 필드는 "권장 인터페이스 목록"의 해당 문서에 있습니다.

# 1) 생성 제출: 1회 0.6위안, 2곡 반환
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Korean pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) status가 completed가 될 때까지 폴링(3~5초 간격 권장)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "1단계에서 받은 song_id"}'

# 3) 미디어 주소 받기: 읽기 계열은 무료이며 song / wav / video / cover / midi를 지정할 수 있습니다
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "같은 song_id", "kind": "song"}'

문제가 생겼을 때의 진입점: 401 / 402 / 403 / 429는 오류 목록을, 타임아웃과 이중 과금은 위의 "대기 시간과 타임아웃 설정"을, 인터페이스별 설명은 아래 "권장 인터페이스 목록"을 보세요.

활용 권장 사항

• 신규 연동은 suno-v6로 통일하는 것을 권장합니다.
• 기본 가격을 적어 둔 인터페이스도 실제 청구 금액은 현재 관리자 가격 설정과 요청 모델을 따릅니다.
• 생성 인터페이스는 보통 작업을 먼저 반환하고, 최종 오디오는 /api/music/query로 조회합니다.
• wait_completion=true는 완료까지 블로킹하므로 저빈도 테스트에 적합합니다. 운영 환경에서는 비동기 조회를 권장합니다.
• 생성 인터페이스는 응답까지 오래 걸릴 수 있습니다. 클라이언트 타임아웃을 300초 이상으로 설정하고, "응답 없음"이 "생성되지 않음"과 다르다는 점에 유의하세요(위 "대기 시간과 타임아웃 설정" 참고).
• 업로드, 커버, 교체, WAV 같은 기능은 플랫폼 계정과 소스 clip 권한에 의존합니다. 실패하면 반환된 message나 error_message를 먼저 확인하세요.

버전 안내

이 문서는 현재 Create UI가 실제로 연동한 기능에 맞춰 다시 정리한 것입니다. 신규 연동 고객은 이 절을 먼저 읽어 주세요. 구버전 인터페이스 문서는 "구버전 인터페이스 문서(호환)" 절에 남아 있으며, 기존 고객은 이전 방식대로 호출할 수 있습니다.