Suno API 키 생성과 401 오류 해결

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

Suno API 키를 콘솔에서 만들고 Authorization: Bearer ...로 첫 요청을 테스트합니다. 401·403·429 오류와 키 보관 방법도 설명합니다.

30초 시작: 콘솔 토큰 페이지에서 키를 만들고 인증된 조회 요청을 한 번 실행하세요. 401이 나오면 키 누락, Bearer 뒤의 공백, 복사된 줄바꿈, 삭제된 키를 먼저 확인합니다.

API 키란

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

키 발급

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

키는 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를 호출하고, 사용자에게는 여러분의 엔드포인트를 노출하세요.

환경 변수 사용

Linux / macOS

# ~/.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

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

Windows

setx SUNO_API_KEY "sk-your-key-here"

Node.js

require('dotenv').config();
const apiKey = process.env.SUNO_API_KEY;

필요할 때 키 교체

키는 3~6개월마다, 유출이 의심되면 즉시 교체하세요. 더 이상 쓰지 않는 키는 삭제하세요. 사용하지 않는 키는 사용하지 않는 위험일 뿐입니다.

요청 제한

요청은 키 단위로 제한됩니다:

429 Too Many Requests

제한을 넘으면 API가 429를 반환하며, 응답에 retry_after(초)가 포함될 수 있습니다. 그만큼 기다린 뒤 다시 시도하세요. 요청 빈도를 낮추거나, 큐에 넣거나, 지수 백오프로 재시도해 부하를 고르게 하세요.

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

재시도 방침

재시도는 명확한 실패에만 하세요. 읽기 타임아웃이나 연결 타임아웃 뒤에는 재시도하지 마세요: 생성 계열 엔드포인트는 동기 방식이라 타임아웃이어도 이미 접수되어 생성 중일 수 있습니다. 재시도하면 주문이 중복되고 요금이 두 번 청구됩니다. 클라이언트 타임아웃을 300초 이상으로 두고, 연결이 끊겼다면 GET /api/music/songs로 접수 여부를 확인한 뒤 다시 보내세요. 자세한 내용은 새 API 개요의 "대기 시간과 타임아웃 설정"을 참고하세요.

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

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-로 시작하고 그 뒤에 영문자와 숫자가 이어집니다. 전체 길이는 약 50~60자입니다.

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

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

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

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

키를 분실했습니다.

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

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

정해진 상한은 없습니다. 애플리케이션·환경별로 키를 나누면 개별 폐기가 쉬우며, 쓰지 않는 키는 삭제하세요.

키에 만료 기한이 있나요?

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

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

콘솔에 로그인하면 키별 사용량(요청 수, 지출, 최근 작업)을 확인할 수 있습니다.

관련 문서

• 빠른 시작 가이드
• 지원 모델