Suno API 사용법: 첫 곡 생성과 다운로드

2026-11-06 업데이트 · Suno-API 팀

Suno API 사용법은 4단계입니다. API 키 생성 후 /api/music/create로 곡을 만들고 song_id로 확인해 MP3/WAV를 다운로드합니다. 1회 0.6위안.

모든 예시는 그대로 복사해 실행할 수 있습니다.

30초 시작: 콘솔 토큰 페이지에서 API 키를 만든 뒤 첫 요청을 보내세요. 생성은 1회 0.6위안이며 2곡을 반환하고, 조회와 다운로드는 별도 요금이 없습니다.

바로 시작하기: API 키와 인증 → API 개요 → Python 예시 → 음원 다운로드

현재 기본 생성 모델은 suno-v6입니다. suno-v2부터 suno-v5-5까지의 일반 생성 모델은 종료되었으며, 과거 작업에는 남아 있을 수 있지만 새 요청에는 사용할 수 없습니다.

다음 주소에서 suno-api agent kit을 다운로드, 설치 및 구성하세요  https://www.suno-api.io/suno-agent-kit.zip

추천: AI가 연결을 완료하도록 하기

AI가 00_START_HERE.md를 읽고 회원가입, API Key 저장, 잔액 확인, 전체 기능 소개 및 첫 생성을 도와줍니다. 유료 작업은 실행 전 확인하며 timeout 시 자동으로 다시 요청하지 않습니다.

1단계: API 키 발급

1. https://www.suno-api.io 에 접속합니다.
2. API 키 받기를 눌러 가입하거나 로그인합니다. 이메일 주소만 있으면 되고 휴대폰 번호는 필요하지 않습니다.
3. 콘솔의 토큰 관리에서 새 키를 만듭니다.
4. 키는 한 번만 표시되므로 즉시 복사하세요. 첫 유료 호출 전에 교환 코드로 잔액을 충전합니다.

2단계: 요청 설정

모든 호출은 동일한 기본 URL과 헤더를 사용합니다.

POST https://www.suno-api.io
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

3단계: 첫 요청 보내기

예시 1 — 한 줄 설명으로 생성

곡을 설명하면 가사, 멜로디, 편곡까지 자동으로 만들어집니다.

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "description": "봄날의 첫날을 노래한 경쾌한 포크",
    "model": "suno-v6"
  }'

응답 예시:

[
  {
    "song_id": "abc123",
    "status": "pending",
    "song_title": "봄의 이야기",
    "description": "봄날의 첫날을 노래한 경쾌한 포크",
    "created_at": "2026-04-22T10:30:00Z"
  },
  {
    "song_id": "def456",
    "status": "pending",
    "song_title": "봄의 발걸음",
    "description": "봄날의 첫날을 노래한 경쾌한 포크",
    "created_at": "2026-04-22T10:30:00Z"
  }
]

1회 생성에 서로 다른 두 가지 버전이 반환되므로 더 마음에 드는 쪽을 고르면 됩니다. 비용은 1회 0.6위안입니다.

예시 2 — 생성 진행 상황 조회

반환된 song_id 값을 조회 API에 전달합니다.

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": ["abc123", "def456"],
    "model": "suno-v6"
  }'

생성 중일 때:

[
  {
    "song_id": "abc123",
    "status": "processing",
    "song_title": "봄의 이야기",
    "progress": "60%"
  }
]

완료되었을 때:

[
  {
    "song_id": "abc123",
    "status": "completed",
    "song_title": "봄의 이야기",
    "audio_url": "https://media.code-go.com/assets/abc123-mp3.mp3",
    "video_url": "https://media.code-go.com/assets/abc123-mp4.mp4",
    "cover_url": "https://media.code-go.com/assets/abc123-cover.jpg",
    "duration": 168
  }
]

status는 pending, submitted, processing을 거쳐 completed로 이동합니다. 작업이 진행 중일 때는 주소가 비어 있을 수 있으므로, audio_url의 유무가 아니라 status를 기준으로 판단하세요.

4단계: 파일 다운로드

status가 completed가 되면 audio_url을 그대로 요청하면 됩니다. MP3와 WAV 다운로드는 횟수 제한이 없고 추가 비용도 없습니다. 추가 편집을 위해 무손실 원본이 필요하면 WAV API를 사용하세요.

⚠️ 미디어 URL은 7일 후 만료됩니다. audio_url(및 WAV 등 미디어 링크)은 당사 오브젝트 스토리지에서 제공됩니다. 7일 이내에 자체 저장소로 옮겨 보관하세요. 만료 후에는 기존 링크가 404가 되지만, 곡 조회 API를 다시 호출하면 새로운 유효 URL을 받을 수 있습니다(재생성 불필요, 추가 과금 없음).

자주 쓰는 시나리오

영상 배경 음악

{
  "description": "제품 소개 영상용 잔잔한 로파이 배경 음악, 보컬 없음, 기복이 크지 않음",
  "instrumental": true,
  "model": "suno-v6"
}

instrumental을 true로 설정하면 보컬 없이 연주만 생성됩니다.

직접 쓴 가사와 스타일 지정

{
  "lyrics": "[Verse 1]\n도시의 불빛이 천천히 흐려져\n\n[Chorus]\n우리는 계속 걸어가",
  "style": "acoustic pop, 따뜻한 여성 보컬, 92 BPM",
  "model": "suno-v6"
}

완료될 때까지 폴링

import time
import requests

API_KEY = "sk-your-key-here"
BASE = "https://www.suno-api.io"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

created = requests.post(
    f"{BASE}/api/music/create",
    headers=HEADERS,
    json={"description": "봄날의 첫날을 노래한 경쾌한 포크", "model": "suno-v6"},
).json()

song_ids = [track["song_id"] for track in created]

for _ in range(60):
    time.sleep(10)
    tracks = requests.post(
        f"{BASE}/api/music/query",
        headers=HEADERS,
        json={"song_ids": song_ids, "model": "suno-v6"},
    ).json()
    if all(track.get("status") == "completed" for track in tracks):
        for track in tracks:
            print(track["song_title"], track["audio_url"])
        break

오류 처리

주요 상태 코드

오류 응답 형식

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

대기 시간과 타임아웃(중요): 생성 계열 엔드포인트는 동기 방식이며, 응답이 돌아온 시점에야 주문이 접수되어 생성에 넘겨집니다. 실측 기준 대부분의 요청은 1~3초에 반환되고, 약 10%는 30초를 넘기며, 최장 약 230초가 걸립니다. 클라이언트 타임아웃을 300초 이상(위 예시의 --max-time 300)으로 설정하세요. 응답이 없다고 해서 생성되지 않은 것이 아니며, 타임아웃 직후 재시도하면 주문이 중복되고 요금이 두 번 청구됩니다. 연결이 끊겼다면 잠시 후 GET /api/music/songs로 확인할 수 있습니다. 자세한 내용은 새 API 개요의 "대기 시간과 타임아웃 설정"을 참고하세요.

권장 사항

• 키는 서버에서만 사용하세요. 브라우저나 배포되는 앱에 넣지 마세요.
• 폴링 간격은 10~15초가 적당합니다. 너무 촘촘하게 반복하지 마세요.
• song_id를 저장하세요. 생성된 음원을 나중에 다시 가져오는 유일한 식별자입니다.
• 429와 500은 재시도하고, 400과 401은 원인을 고친 뒤 보내세요.
• 실패한 생성은 자동으로 환불되므로 비용이 발생하지 않습니다.
• 클라이언트 타임아웃: 생성 계열 엔드포인트는 응답이 돌아와야 접수가 끝납니다. 타임아웃은 300초 이상으로 설정하세요.
• 재시도: 명확한 실패 응답(4xx/5xx)에만 재시도하세요. 연결 타임아웃이나 끊김 후에는 먼저 GET /api/music/songs로 접수 여부를 확인해 주문 중복과 이중 청구를 피하세요.

다음 단계

• 인증 안내 — 키 관리, 오류, 요청 제한
• 지원 모델 — 모델명, 스템 분리, 종료된 모델