인증 안내

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

Suno-API의 모든 요청은 API 키로 인증합니다. 이 문서에서는 키 발급, 전송 방법, 오류 응답의 의미, 키를 안전하게 관리하는 방법을 다룹니다.

API 키란

API 키는 계정에 연결된 베어러 토큰입니다. 잔액을 그대로 사용할 수 있으므로, 키를 가진 사람은 누구든 잔액을 소비할 수 있습니다. 키는 발급 시 한 번만 표시되므로 즉시 복사해 안전한 곳에 보관하세요.

키 발급

https://www.suno-api.io 에서 가입합니다. 이메일 주소만 있으면 되고 휴대폰 번호는 필요하지 않습니다.
콘솔에서 토큰 관리로 이동합니다.
새 키를 만들고 복사합니다.

키는 sk-… 형태입니다. 분실한 키는 복구할 수 없으므로 새로 발급하고 기존 키를 삭제하세요.

키 사용

모든 요청의 Authorization 헤더에 키를 담아 보냅니다.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

예시

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "카페에 어울리는 잔잔한 피아노 연주"}'

인증 오류

401 Unauthorized

헤더가 없거나 형식이 잘못되었거나, 키가 존재하지 않는 경우입니다.

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

헤더가 정확히 Bearer <키> 형태인지(Bearer 뒤에 공백), 키 끝에 줄바꿈이 섞이지 않았는지 확인하세요.

403 Forbidden

키는 유효하지만 이 요청을 수행할 수 없는 경우이며, 대부분 잔액 부족입니다. 충전 후 같은 요청을 다시 보내세요.

보안 권장 사항

키를 클라이언트 코드에 넣지 마세요

웹 페이지, 모바일 앱, 데스크톱 바이너리에 키를 넣지 마세요. 개발자 도구를 열 수 있는 사용자라면 누구든 키를 읽고 잔액을 소비할 수 있습니다. 자체 서버에서 API를 호출하고, 사용자에게는 여러분의 엔드포인트를 노출하세요.

환경 변수 사용

# ~/.bashrc 또는 ~/.zshrc
export SUNO_API_KEY="sk-your-key-here"

# 코드에서
curl -H "Authorization: Bearer $SUNO_API_KEY" ...

# 파이썬
import os
api_key = os.environ["SUNO_API_KEY"]

# .env 파일 — 반드시 .gitignore에 추가하세요
SUNO_API_KEY=sk-your-key-here

필요할 때 키 교체

키가 유출되었을 가능성이 있다면 새 키를 만들고 기존 키를 삭제하세요. 교체 비용은 거의 없지만, 노출된 키의 대가는 큽니다.

요청 제한

요청은 키 단위로 제한됩니다. 한도를 넘으면 429 Too Many Requests가 반환됩니다.

{
  "error": {
    "message": "Rate limit exceeded, please retry later",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

짧은 간격으로 반복 호출하지 말고 지수 백오프로 재시도하세요.

import time

delay = 1.0
for attempt in range(5):
    response = call_api()
    if response.status_code != 429:
        break
    time.sleep(delay)
    delay *= 2

자주 묻는 질문

API 키 형식은 어떻게 되나요?

sk-로 시작하고 뒤에 임의 문자열이 붙습니다. 전체를 하나의 토큰으로 취급하세요.

브라우저에서 바로 호출해도 되나요?

기술적으로는 가능하지만 운영 환경에서는 권장하지 않습니다. 키가 모든 방문자에게 노출됩니다. 자체 백엔드를 통해 프록시하세요.

키가 아직 유효한지 어떻게 확인하나요?

인증이 필요한 아무 요청이나 보내보세요. 200이면 정상, 401이면 유효하지 않거나 삭제된 키입니다.

키를 분실했습니다.

키는 복구할 수 없습니다. 콘솔에서 새로 발급하고 기존 항목을 삭제하세요.

계정 하나에 키를 몇 개까지 만들 수 있나요?

여러 개를 만들 수 있습니다. 애플리케이션 또는 환경별로 키를 분리하면 개별 폐기가 가능합니다.

키에 만료 기한이 있나요?

직접 삭제하거나 계정을 닫기 전까지 유효합니다. 정기적인 교체를 권장합니다.

사용량은 어떻게 확인하나요?

콘솔에서 잔액과 사용 내역을 확인할 수 있습니다. 생성 1회에 0.6위안이며 2곡이 반환되고, 실패한 생성은 자동으로 환불됩니다.