프로 모드 생성 API

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

인터페이스 설명

프로 모드는 가사, 스타일, 제목이 이미 준비되어 있고 노래 목소리, 스타일 참고 강도, 생성의 무작위 정도까지 제어하고 싶은 경우에 적합합니다.

엔드포인트: POST /api/music/create/custom

과금: 유료, 현재 기본 1회 0.6위안. 보통 1회 호출에 2곡이 반환되며, 실제 청구 금액은 현재 백오피스 가격 설정을 따릅니다.

Max Mode / Variety: 이 엔드포인트는 선택 파라미터 max_mode와 variety(0-4)를 지원합니다. max_mode를 켜면 이번 호출은 2배 가격으로 과금되며(0.6 → 1.2위안/회), variety는 추가 과금이 없습니다. 두 값의 의미와 사용법은 새 API 개요의 "고급 파라미터" 절을 참고하세요.

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

요청 파라미터

Headers

Body 파라미터

고급 파라미터 설명

목소리 성별 vocal_gender

• 남성은 m 또는 male, 여성은 f 또는 female을 보냅니다.
• 서버는 male, female을 각각 m, f로 정규화합니다.
• instrumental=true일 때는 목소리 성별 파라미터를 생성 서비스로 보내지 않습니다.

스타일 참고도 style_weight

생성 결과가 style_tags를 얼마나 따르는지 제어합니다. 값이 높을수록 입력한 스타일 태그를 따르는 결과가 나오기 쉽습니다.

무작위도 weirdness_constraint

생성 결과의 변화와 실험적 성향을 제어합니다. 값이 높으면 변화가 커지고, 낮으면 무난한 결과가 나오기 쉽습니다.

두 숫자 파라미터의 범위는 모두 0.0~`1.0이며 0`도 유효한 명시 값입니다. 필드를 아예 보내지 않을 때만 "지정하지 않음"을 뜻합니다.

입력할 때 주의하세요. 이 값들은 비율을 나타내는 소수이고 퍼센트 정수가 아닙니다. 참고 기준: 0.00.3은 보수적, 0.40.6은 균형, 0.7~`1.0은 실험적입니다. 뚜렷한 선호가 없으면 0.5를 쓰거나 그냥 생략해도 됩니다. 예: weirdness_constraint: 0.5, 50이나 50%`는 쓰지 마세요.

instrumental=true이면 순수 연주곡이 생성되므로 가사와 목소리 성별은 노래곡처럼 작동하지 않습니다. 보컬이 필요하면 false를 보내거나 그 필드를 생략하세요. 불리언 필드는 JSON의 true/false를 사용하고 문자열은 쓰지 마세요.

Python 요청 예시

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\n밤이 바다 위로 내리고\n저녁 바람이 창가를 지나간다',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': '바닷가의 저녁 바람',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

접수 영수증 모드(선택)

이 엔드포인트도 영감 모드 생성 API의 접수 영수증 모드를 지원합니다. 요청 본문에 "accept_mode": "async"(또는 헤더 X-Accept-Mode: async)를 넣으면 인터페이스가 즉시 202와 접수 번호를 반환하고 생성은 백그라운드에서 계속됩니다. 진행 상황은 GET /api/music/requests/{request_id}로 조회합니다.

클라이언트가 긴 연결을 유지하기 어렵거나, 타임아웃 때문에 "생성되지 않았다"고 잘못 판단하고 싶지 않은 경우에 적합합니다. 이 파라미터를 넣지 않으면 동작은 기존과 완전히 같습니다.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "바닷가의 저녁 바람",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

반환 구조와 폴링 방법은 영감 모드 생성 API의 "접수 영수증 모드" 절을 참고하세요.

파라미터 검증

다음 경우 HTTP 400을 반환하며, 오류 응답의 message가 어떤 필드가 잘못되었는지 알려 줍니다:

• style_weight 또는 weirdness_constraint가 숫자가 아님.
• 숫자가 0.0 미만이거나 1.0 초과.
• vocal_gender가 m, f, male, female 중 하나가 아님.

텍스트 필드 길이 상한

다음 필드도 초과 시 HTTP 400을 반환하며, 생성에 들어가지 않고 선차감도 되지 않습니다. 계산은 유니코드 문자 기준(한자 1자는 1자)이고 앞뒤 공백도 포함합니다:

오류 메시지는 style_tags must not exceed 1000 characters; received 2772 형태입니다. 앞 단어가 초과한 필드명이고 끝이 실제 글자 수이므로, 400을 받으면 그 두 숫자로 바로 잘라내면 되고 필드를 하나씩 시도할 필요가 없습니다. 공통 규칙은 새 API 개요의 "텍스트 필드 상한"에 있습니다.

응답 결과

보통 2곡을 담은 배열을 반환합니다. 비동기 요청의 초기 상태는 보통 pending이므로 song_id를 저장하고 곡 조회 API로 최종 상태와 오디오 주소를 가져오세요. 곡 필드는 영감 모드 생성 API와 같습니다.

호환 필드

새 연동은 snake_case로 통일하세요. 한 요청에 snake_case와 camelCase를 함께 보내면 snake_case 값이 우선합니다.