메인 콘텐츠로 건너뛰기
POST
/
v1
/
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-v4.5", "prompt": "A cheerful summer pop song about road trips and freedom" } '
{
  "created": 1766319090,
  "id": "task-unified-1766319089-oqs9cue4",
  "model": "suno-v5",
  "object": "audio.generation.task",
  "progress": 100,
  "result_data": [
    {
      "result_id": "555f4ea2-cfef-4622-8355-baa5f2ce6a59",
      "duration": 91.2,
      "tags": "R&B",
      "title": "Forget Me Nots",
      "image_url": "https://media.evolink.ai/xxx.jpeg",
      "audio_url": "https://media.evolink.ai/xxx.mp3",
      "stream_audio_url": "https://media.evolink.ai/xxx.mp3"
    }
  ],
  "results": [
    "https://media.evolink.ai/xxx.mp3",
    "https://media.evolink.ai/yyy.mp3"
  ],
  "status": "completed",
  "task_info": {
    "can_cancel": false
  },
  "type": "audio"
}

인증

​
Authorization
string
header
필수

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

API Key 받기:

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

요청 헤더에 추가:

Authorization: Bearer YOUR_API_KEY

본문

application/json
​
model
enum<string>
필수

모델 이름

사용 가능한 옵션:

  • suno-v4: V4 버전, 향상된 보컬 품질, 최대 4분, 프롬프트 최대 3000자, 스타일 최대 200자
  • suno-v4.5: V4.5 버전 (권장), 더 스마트한 프롬프트, 더 빠른 생성, 최대 8분, 프롬프트 최대 5000자, 스타일 최대 1000자
  • suno-v4.5plus: V4.5+ 향상 버전, 더 풍부한 톤, 새로운 창작 방법, 최대 8분, 프롬프트 최대 5000자, 스타일 최대 1000자
  • suno-v4.5all: V4.5 전체 기능 버전, 더 스마트한 프롬프트, 더 빠른 생성, 최대 8분, 프롬프트 최대 5000자, 스타일 최대 1000자
  • suno-v5: V5 최신 버전, 뛰어난 음악 표현력, 더 빠른 생성, 프롬프트 최대 5000자, 스타일 최대 1000자
사용 가능한 옵션:
suno-v4,
suno-v4.5,
suno-v4.5plus,
suno-v4.5all,
suno-v5
예시:

"suno-v4.5"

​
custom_mode
boolean
필수

커스텀 모드 활성화

설명:

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

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

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

false

​
instrumental
boolean
필수

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

설명:

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

참고:

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

false

​
prompt
string

모션 및 카메라 움직임을 설명하는 프롬프트, 선택 사항. 최대 2000자

15가지 카메라 명령:

  • 트럭: [Truck left], [Truck right]
  • 팬: [Pan left], [Pan right]
  • 돌리: [Push in], [Pull out]
  • 페데스탈: [Pedestal up], [Pedestal down]
  • 틸트: [Tilt up], [Tilt down]
  • 줌: [Zoom in], [Zoom out]
  • 특수: [Shake]
  • 팔로우: [Tracking shot]
  • 정적: [Static shot]

사용법:

  • 결합: 하나의 []에 여러 명령을 동시에 실행, 예: [Pan left,Pedestal up], 최대 3개 권장
  • 순차: 명령은 텍스트 순서대로 실행, 예: ...천천히 [Push in], 그런 다음 빠르게 [Pull out]
예시:

"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
예시:

"pop, electronic, upbeat, female vocals"

​
title
string

곡 제목

설명:

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

"Summer Dreams"

​
negative_tags
string

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

예시:

  • heavy metal, screaming, sad
  • rap, fast tempo
예시:

"heavy metal, screaming"

​
vocal_gender
enum<string>

보컬 성별 선호

옵션:

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

참고:

  • custom_mode=true일 때만 적용됩니다
  • 이 매개변수는 확률만 높이며, 지정된 성별이 반드시 따라지는 것을 보장하지 않습니다
사용 가능한 옵션:
m,
f
예시:

"f"

​
style_weight
number

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

범위: 0.0 ~ 1.0, 소수점 한 자리

설명:

  • 높은 값일수록 지정된 스타일에 더 가깝게 준수합니다
  • 0 값은 미설정으로 처리됩니다
필수 범위: 0 <= x <= 1
예시:

0.7

​
weirdness_constraint
number

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

범위: 0.0 ~ 1.0, 소수점 한 자리

설명:

  • 높은 값일수록 더 창의적이고 실험적인 출력
  • 낮은 값일수록 더 전통적이고 보수적인 출력
  • 0 값은 미설정으로 처리됩니다
필수 범위: 0 <= x <= 1
예시:

0.3

​
audio_weight
number

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

범위: 0.0 ~ 1.0, 소수점 한 자리

설명:

  • 0 값은 미설정으로 처리됩니다
필수 범위: 0 <= x <= 1
예시:

0.5

​
callback_url
string<uri>

작업 완료 알림을 위한 HTTPS 콜백 URL

콜백 단계:

  • 콜백 프로세스는 세 단계로 구성: text (텍스트 생성), first (첫 번째 트랙 완료), complete (모두 완료)
  • 경우에 따라 text 및 first 단계가 건너뛰어지고 complete가 직접 반환될 수 있음

보안 제한:

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

콜백 메커니즘:

  • 타임아웃: 10초
  • 실패 시 최대 3회 재시도
  • 콜백 URL이 2xx 상태 코드를 반환하면 성공으로 간주
예시:

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

응답

음악 스타일 지정

설명:

  • 사용자 정의 모드(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
​
created
integer

작업 생성 타임스탬프

예시:

1766319090

​
id
string

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

예시:

"task-unified-1766319089-oqs9cue4"

​
model
string

실제 사용된 모델 이름

예시:

"suno-v5"

​
object
enum<string>

작업 유형

사용 가능한 옵션:
audio.generation.task
​
progress
integer

작업 진행률 (0-100)

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

100

​
result_data
object[]

생성된 음악 상세 배열, 작업 완료 시 반환됩니다

​
results
string<uri>[]

생성된 오디오 URL 배열, 작업 완료 시 반환됩니다

예시:
[
  "https://media.evolink.ai/xxx.mp3",
  "https://media.evolink.ai/yyy.mp3"
]
​
status
enum<string>

작업 상태

사용 가능한 옵션:
pending,
processing,
completed,
failed
예시:

"completed"

​
task_info
object

오디오 작업 상세

​
type
enum<string>

작업 출력 유형

사용 가능한 옵션:
audio
예시:

"audio"