curl --request POST \
  --url https://api.evolink.ai/v1/audios/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "suno-v5-beta",
  "prompt": "A cheerful summer pop song about road trips and freedom"
}
'

{
  "created": 1766319090,
  "id": "task-unified-1766319089-oqs9cue4",
  "model": "suno-v5-beta",
  "object": "audio.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 120
  },
  "type": "audio",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 10,
    "user_group": "default"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "insufficient_quota",
    "message": "Insufficient quota. Please top up your account.",
    "type": "insufficient_quota"
  }
}

{
  "error": {
    "code": "model_access_denied",
    "message": "Token does not have access to model: suno-v5-beta",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests, please try again later",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "type": "api_error"
  }
}

{
  "error": {
    "code": "service_unavailable",
    "message": "No available channel for the requested model",
    "type": "api_error"
  }
}

Suno

Suno 음악 생성 Beta

Suno AI 음악 생성 모델, 텍스트 설명 또는 가사를 기반으로 완전한 음악 생성 지원
커스텀 모드 (스타일, 제목, 가사 세밀 제어) 및 심플 모드 (AI 자동 생성) 지원
Persona 기능 지원, 생성된 보컬/스타일 특성을 재사용할 수 있습니다
비동기 처리 모드, 반환된 작업 ID로 상태 조회
생성된 오디오 링크는 72시간 동안 유효하며, 즉시 저장해 주세요
각 요청마다 여러 음악 변형이 생성됩니다

POST

audios

generations

curl --request POST \
  --url https://api.evolink.ai/v1/audios/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "suno-v5-beta",
  "prompt": "A cheerful summer pop song about road trips and freedom"
}
'

{
  "created": 1766319090,
  "id": "task-unified-1766319089-oqs9cue4",
  "model": "suno-v5-beta",
  "object": "audio.generation.task",
  "progress": 0,
  "status": "pending",
  "task_info": {
    "can_cancel": true,
    "estimated_time": 120
  },
  "type": "audio",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 10,
    "user_group": "default"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "insufficient_quota",
    "message": "Insufficient quota. Please top up your account.",
    "type": "insufficient_quota"
  }
}

{
  "error": {
    "code": "model_access_denied",
    "message": "Token does not have access to model: suno-v5-beta",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests, please try again later",
    "type": "rate_limit_error"
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error",
    "type": "api_error"
  }
}

{
  "error": {
    "code": "service_unavailable",
    "message": "No available channel for the requested model",
    "type": "api_error"
  }
}

인증

Authorization

string

header

필수

##모든 API는 Bearer Token 인증이 필요합니다##

API Key 받기:

API Key 관리 페이지를 방문하여 API Key를 받으세요

요청 헤더에 추가:

Authorization: Bearer YOUR_API_KEY

본문

application/json

model

enum<string>

필수

모델 이름

하위 호환성: 이전에 통합된 모델명(예: suno-v5, suno-v4.5, suno-v4.5plus, suno-v4.5all, suno-v4)은 계속 사용 가능하며, 해당 -beta 버전으로 자동 매핑됩니다

사용 가능한 옵션:

suno-v5.5-beta: 고유한 취향에 맞춘 모델을 지원하는 V5.5, 프롬프트 최대 5000자, 스타일 최대 1000자; 호환 모델명: suno-v5.5
suno-v5-beta: V5 최신 버전 (기본 권장), Voice Persona 지원, 뛰어난 음악 표현력, 더 빠른 생성, 프롬프트 최대 5000자, 스타일 최대 1000자
suno-v4.5plus-beta: V4.5+ 향상 버전, 더 풍부한 톤, 새로운 창작 방법, 최대 8분, 프롬프트 최대 5000자, 스타일 최대 1000자
suno-v4.5all-beta: V4.5 전체 기능 버전, 더 스마트한 프롬프트, 더 빠른 생성, 최대 8분, 프롬프트 최대 5000자, 스타일 최대 1000자
suno-v4.5-beta: V4.5 버전, 더 스마트한 프롬프트, 더 빠른 생성, 최대 8분, 프롬프트 최대 5000자, 스타일 최대 1000자
suno-v4-beta: V4 버전, 향상된 보컬 품질, 최대 4분, 프롬프트 최대 3000자, 스타일 최대 200자

사용 가능한 옵션:

suno-v5.5-beta,

suno-v5-beta,

suno-v4.5plus-beta,

suno-v4.5all-beta,

suno-v4.5-beta,

suno-v4-beta

예시:

"suno-v5-beta"

custom_mode

boolean

기본값:false

커스텀 모드 활성화

설명:

false: 심플 모드, prompt만 제공하면 AI가 가사와 스타일을 자동 생성
true: 커스텀 모드, style, title, 가사 등을 세밀하게 제어 가능

커스텀 모드 필수 파라미터:

style: 필수
title: 필수
prompt: instrumental=false일 때 필수 (가사로 사용)

심플 모드(custom_mode=false)에서는 prompt만 지원됩니다: style, title, negative_tags, vocal_gender, style_weight, weirdness_constraint, audio_weight, persona_id, persona_model, duration은 이 모드에서 모두 지원되지 않습니다. API가 반드시 거부한다고 보장하지는 않지만, 이 매개변수들은 생성 결과에 아무런 영향을 주지 않습니다. 세밀한 제어가 필요하면 custom_mode=true를 사용하세요

예시:

false

instrumental

boolean

기본값:false

인스트루멘탈 음악 생성 (보컬 없음)

설명:

false: 보컬이 포함된 음악 생성
true: 보컬 없는 인스트루멘탈/배경 음악 생성

참고:

비커스텀 모드에서는 이 파라미터가 필수 필드에 영향을 주지 않습니다
커스텀 모드에서 true로 설정하면 prompt가 선택 사항이 됩니다

예시:

false

prompt

string

프롬프트, 원하는 음악 내용을 설명합니다

비커스텀 모드 (custom_mode=false):

필수, 음악 설명으로 사용되며 AI가 가사와 스타일을 자동 생성
최대 길이: 500자

커스텀 모드 (custom_mode=true):

instrumental=false일 때 필수, 정확한 가사로 사용
instrumental=true일 때 선택 사항
최대 길이: V4는 3000자, V4.5+는 5000자

가사 형식 제안:

[Verse], [Chorus], [Bridge] 등의 태그로 가사 구조를 구성하세요

예시:

"A cheerful summer pop song about road trips and freedom"

style

string

음악 스타일 지정

설명:

사용자 정의 모드(custom_mode=true)에서 필수
음악의 장르, 분위기 또는 예술적 방향을 정의합니다
영어로 쉼표로 구분된 태그 사용을 권장합니다

문자 제한:

V4: 최대 200자
V4.5+: 최대 1000자

일반적인 스타일 태그:

장르: pop, rock, jazz, classical, electronic, hip-hop, r&b, country, folk
분위기: happy, sad, energetic, calm, romantic, dark, uplifting
악기: piano, guitar, drums, bass, violin, saxophone, synthesizer
보컬: male vocals, female vocals, choir, harmonies
템포: slow, fast, upbeat, groovy, 120bpm

심플 모드(custom_mode=false)에서는 지원되지 않습니다. 이 모드에서는 AI가 prompt를 바탕으로 스타일을 자동 생성하므로 이 매개변수를 전송해도 적용되지 않습니다.

예시:

"pop, electronic, upbeat, female vocals"

title

string

곡 제목

설명:

사용자 정의 모드(custom_mode=true)에서 필수
플레이어 인터페이스 및 파일명에 표시됩니다
최대 길이: 80자

심플 모드(custom_mode=false)에서는 지원되지 않습니다. 이 모드에서는 AI가 제목을 자동 생성하므로 이 매개변수를 전송해도 적용되지 않습니다.

Maximum string length: 80

예시:

"Summer Dreams"

negative_tags

string

제외 스타일, 피하고 싶은 음악 스타일이나 특성을 지정합니다

설명:

최대 길이: 200자 (모든 모델 동일)

예시:

heavy metal, screaming, sad
rap, fast tempo

custom_mode=true일 때만 지원됩니다. 심플 모드에서 전송해도 적용되지 않습니다.

Maximum string length: 200

예시:

"heavy metal, screaming"

vocal_gender

enum<string>

보컬 성별 선호

옵션:

m: 남성 목소리
f: 여성 목소리

참고:

custom_mode=true일 때만 적용됩니다
이 매개변수는 확률만 높이며, 지정된 성별이 반드시 따라지는 것을 보장하지 않습니다
심플 모드(custom_mode=false)에서는 지원되지 않으며, 전송해도 적용되지 않습니다

사용 가능한 옵션:

m,

f

예시:

"f"

style_weight

number

스타일 가중치, 지정된 스타일 준수 강도를 제어합니다

범위: 0.0 ~ 1.0, 소수점 이하 최대 두 자리이며 0.01의 배수

설명:

값이 높을수록 지정된 스타일을 더 강하게 따릅니다
0은 유효한 값으로 지정 스타일을 따르지 않음을 의미하며 모델에 전달됩니다

custom_mode=true일 때만 지원됩니다. 심플 모드에서 전송해도 적용되지 않습니다.

필수 범위: 0 <= x <= 1다음의 배수여야 합니다 0.01

예시:

0.7

weirdness_constraint

number

기이함 제약, 출력의 창의성/실험성 정도를 제어합니다

범위: 0.0 ~ 1.0, 소수점 이하 최대 두 자리이며 0.01의 배수

설명:

값이 높을수록 더 창의적이고 실험적인 결과가 생성됩니다
값이 낮을수록 더 전통적이고 보수적인 결과가 생성됩니다
0은 유효한 값이며 모델에 전달됩니다

custom_mode=true일 때만 지원됩니다. 심플 모드에서 전송해도 적용되지 않습니다.

필수 범위: 0 <= x <= 1다음의 배수여야 합니다 0.01

예시:

0.3

audio_weight

number

오디오 가중치, 오디오 특성의 가중치를 제어합니다

범위: 0.0 ~ 1.0, 소수점 이하 최대 두 자리이며 0.01의 배수

설명:

0은 유효한 값이며 모델에 전달됩니다

custom_mode=true일 때만 지원됩니다. 심플 모드에서 전송해도 적용되지 않습니다.

필수 범위: 0 <= x <= 1다음의 배수여야 합니다 0.01

예시:

0.5

persona_id

string

Persona ID, 이미 생성된 Persona 스타일을 이번 음악 생성에 적용합니다

custom_mode=true일 때만 사용 가능합니다. Suno Persona 생성 API를 통해 획득하며, 적용 후 일관된 보컬 및 스타일 특성을 유지할 수 있습니다

획득 방법: Persona 작업 완료 후 result_data.persona_id에서 가져옵니다

심플 모드(custom_mode=false)에서는 지원되지 않습니다.

V5 계열 모델(suno-v5-beta / suno-v5.5-beta 및 해당 -beta 없는 호환 이름)에서만 지원되며, 다른 모델에서 전송하면 매개변수 오류가 반환됩니다.

예시:

"5c57d49ef834110496fae5aa14fec441"

persona_model

enum<string>

Persona 적용 방식

옵션:

style_persona: 스타일 지향형으로 편곡, 리듬, 음색 등 음악 스타일 특성을 중시
voice_persona: 보컬 지향형으로 음색, 창법, 음역 등 보컬 특성을 중시

두 방식 모두 V5 계열 모델(suno-v5-beta / suno-v5.5-beta 및 해당 -beta 없는 호환 이름)에서만 사용할 수 있으며 custom_mode=true가 필요합니다. 반드시 persona_id와 함께 사용해야 하며, persona_id 없이 persona_model만 전송하면 적용되지 않습니다(persona_id는 단독으로 사용할 수 있습니다).

사용 가능한 옵션:

style_persona,

voice_persona

예시:

"style_persona"

duration

integer

기본값:20

요청 오디오 길이(초)

모델이 suno-v5.5-beta(또는 호환 이름 suno-v5.5)이고 custom_mode=true일 때만 사용할 수 있습니다. 10~360 사이의 정수여야 합니다. 생략하면 업스트림 기본값 20초가 사용됩니다. 다른 모델이나 심플 모드에서는 지원되지 않으며, 전송하면 매개변수 오류가 반환됩니다.

필수 범위: 10 <= x <= 360

예시:

120

callback_url

string<uri>

작업 종료 상태 알림을 위한 HTTPS 콜백 URL

콜백 시점:

GroAPI는 작업이 종료 상태(completed, failed, cancelled)에 도달할 때 한 번만 전송합니다
text, first 같은 업스트림 중간 단계는 전달하지 않습니다
콜백 본문은 GET /v1/tasks/{id}의 작업 상세 구조와 동일합니다

보안 제한:

HTTPS만 지원
내부 IP 주소로의 콜백 금지
URL 길이는 2048자를 초과할 수 없음

콜백 메커니즘:

요청당 타임아웃: 10초
최초 요청 실패 후 최대 3회 재시도
2xx 상태 코드를 반환하면 성공으로 간주

예시:

"https://your-domain.com/webhooks/suno-callback"

응답

음악 작업 생성 성공

created

integer

작업 생성 타임스탬프

예시:

1766319090

string

작업 ID, 작업 상태 및 결과를 조회하는 데 사용됩니다

예시:

"task-unified-1766319089-oqs9cue4"

model

string

실제 사용된 모델 이름

예시:

"suno-v5-beta"

object

enum<string>

작업 유형

사용 가능한 옵션:

audio.generation.task

progress

integer

작업 진행률 (0-100)

필수 범위: 0 <= x <= 100

예시:

0

status

enum<string>

작업 상태

사용 가능한 옵션:

pending,

processing,

completed,

failed,

cancelled

예시:

"pending"

task_info

object

오디오 작업 상세

Show child attributes

type

enum<string>

작업 출력 유형

사용 가능한 옵션:

audio

예시:

"audio"

usage

object

사용량 및 과금 정보

Show child attributes

이미지 시리즈

비디오 시리즈

오디오 시리즈

텍스트 시리즈

계정 관리

작업 관리

파일 관리

Suno 음악 생성 Beta

인증

본문

응답