Skip to main content
POST
소스 트랙: 소스는 POST /v1/music/generations/uploadTask로 만든 업로드 작업이어야 합니다. 해당 작업의 task_id를 전달하고 audio_index로 data.result.music[]의 트랙을 선택합니다(1부터 시작, 기본값 1). 일반 생성 작업은 소스로 사용할 수 없습니다.
custom은 적용되는 필드를 제어합니다. 선택한 모드에서 적용되지 않는 필드도 제출했다면 유형, 범위, 길이 요구사항을 충족해야 합니다. custom=true에서는 prompt(가사), title, tags, negative_tags, style_weight, weirdness, audio_weight가 적용되고 gpt_description은 무시됩니다. custom=false에서는 gpt_description만 적용되며 필수이고, 생략하면 제출 시 400이 반환됩니다. vocal_gender는 두 모드 모두에서 적용됩니다. custom을 생략하면 백엔드는 다음 순서로 추론합니다. prompt가 있으면 true, prompt 없이 gpt_description이 있으면 false, 그 외에는 tags 또는 title이 있으면 true입니다.

Authorizations

string
필수
모든 API는 Bearer Token을 사용한 인증이 필요합니다API Key 발급:API Key 관리 페이지에 접속하여 API Key를 발급받으세요사용 시 요청 헤더에 추가하세요:

Body

string
기본값:"suno"
오디오 모델. 현재는 suno를 전달합니다(전달하지 않으면 기본값 suno).
string
필수
POST /v1/music/generations/uploadTask가 반환한 task_id. 일반 생성 작업은 사용할 수 없습니다. 소스가 없거나 잘못되면 제출 시 400을 반환합니다.
integer
기본값:"1"
소스 작업의 data.result.music[]에서 트랙을 선택합니다(1부터 시작, 기본값 1).
string
기본값:"v6"
공개 버전: v6 / v6-wild / v6-mini. 기본값은 v6이며 custom_model_id 사용 시 생략하세요.
string
모델 생성 작업이 반환한 전체 UUID. version과 함께 사용할 수 없습니다.
boolean
true=커스텀 모드(prompt를 가사로 사용); false=영감 모드(gpt_description 사용); 생략하면 콘텐츠로부터 추론됩니다(위의 Warning 참조).
string
가사. custom=true일 때 적용됩니다(영감 모드에서는 무시됨).
string
영감 프롬프트. custom=false일 때 필수 — 없으면 제출 시점에 400으로 실패합니다(과금되지 않음).
string
제목. custom=true일 때만 적용됩니다.
string
스타일 태그. custom=true일 때만 적용됩니다.
string
제외할 스타일 태그. custom=true일 때만 적용됩니다.
number
스타일 가중치, 0.00–1.00(범위를 벗어난 값은 제출 시 바로 400이 반환됩니다). custom=true일 때만 적용됩니다.
number
창의성 가중치, 0.00~1.00. 이전 이름 weirdness_constraint도 지원하지만 새 요청은 weirdness를 사용하세요.
number
오디오 가중치, 0.00–1.00. custom=true일 때만 적용됩니다.
string
보컬 성별: Male / Female. 두 모드 모두에서 적용됩니다.
string
스타일 변화: off / normal / high / extra / max.
boolean
기본값:"false"
Max 모드를 활성화합니다. 커스텀 모드가 필요하며 일반 가격의 2배로 청구됩니다.
string
출력 오디오 형식: mp3 / m4a / wav. 이 엔드포인트는 목표 길이 필드를 지원하지 않습니다.
이 API는 auto_lyrics, persona_id, instrumental, 목표 길이 필드를 지원하지 않습니다.
결과 조회: 비동기 작업입니다. 제출 후 task_id를 받고 status가 completed 또는 failed가 될 때까지 35초마다 GET /v1/music/tasks/{task_id}를 폴링합니다. 음악 생성은 보통 30120초가 걸리며, 처리 중 status는 pending 또는 processing일 수 있고 progress는 0~100의 정수지만 일정 간격으로 변한다고 보장되지 않습니다. 완료 후 data.result.music[]에서 audio_url을 읽습니다. 실패 시 사유는 data.error.message에 있으며 차감 금액은 자동 환불됩니다.

Response

integer
응답 상태 코드
array
반환 데이터 배열