Skip to main content
POST
기존 POST /v1/music/generations/wav 엔드포인트는 더 이상 권장되지 않습니다. 임시 호환을 위해 계속 사용할 수 있으며 새 API에 formats: ["wav"]를 전달한 것과 같습니다. 새 코드는 POST /v1/music/generations/download를 사용하세요.
원본 곡 선택: 원본 오디오를 만든 작업의 task_id를 전달하고 audio_index로 결과 music[]에서 곡을 선택합니다. 인덱스는 1부터 시작하며 기본값은 1입니다.

인증

string
필수
모든 API에 Bearer Token이 필요합니다. API 키 페이지에서 키를 받으세요.

요청 매개변수

string
기본값:"suno"
모델 이름. suno를 사용하며 생략 시에도 suno가 기본값입니다.
string
필수
원본 곡 생성 시 반환된 작업 ID.원본 작업은 현재 계정에 속하고 완료되어야 하며 다운로드 가능한 오디오를 포함해야 합니다. 음악 생성, 연장, 커버, 스템 작업은 사용할 수 있지만 가사나 BPM 분석처럼 텍스트만 반환하는 작업은 사용할 수 없습니다.
integer
기본값:"1"
원본 작업의 music[] 결과에서 다운로드할 곡 번호.
  • 1부터 시작
  • 기본값: 1
  • 원본 작업의 곡 수를 초과할 수 없음
string[]
요청할 파일 형식 배열. 최소 한 항목이 필요합니다.지원 값: mp3, m4a, wav.여러 형식을 함께 요청할 수 있습니다. 대소문자를 구분하지 않고 중복 값은 자동 제거되며 결과 순서는 요청 순서와 같습니다.
string
한 형식만 필요한 경우 formats 대신 사용할 수 있습니다.예: "format": "mp3"
formats 또는 format 중 하나를 사용하세요. 둘 다 생략하거나 빈 배열을 전달하면 HTTP 400을 반환합니다.

제출 응답

성공하면 다운로드 작업의 새 task_id가 반환됩니다.
data는 배열입니다. data[0].task_id를 읽으세요. 이 ID는 새 다운로드 작업 ID이며 요청에 넣은 원본 곡 task_id와 다릅니다.

다운로드 결과 조회

제출 응답의 다운로드 작업 ID를 사용합니다.
파일은 대개 제출 시 이미 준비됩니다. 즉시 한 번 조회하고 상태가 completed 또는 failed가 아니면 2초마다 최대 60초 동안 조회하세요.

완료

다운로드 파일은 result.files[]에서 읽습니다.
result.wavUrl은 기존 WAV API 호환용입니다. 새 코드는 항상 result.files[]를 사용하세요.

처리 중

아직 result가 없습니다. 계속 조회하세요.

실패

실패한 작업은 자동 환불되고 cost: 0을 반환합니다. error.message를 표시하고 다시 시도할 수 있게 하세요.

파일 URL

보통 APIMart 파일 도메인을 반환합니다. 저장 전송이 실패한 경우 유효 기간이 보장되지 않는 업스트림 CDN URL이 반환될 수 있습니다.
URL을 받은 후 즉시 다운로드하고 저장하세요. 임시 URL을 장기 저장소처럼 사용하지 마세요.

오류

검증 오류는 작업 생성 및 과금 전에 HTTP 400을 반환합니다. HTTP 403과 model_price_not_configuredsuno@download 가격이 설정되지 않았다는 뜻입니다. 플랫폼 지원팀에 문의하세요.

과금과 반복 다운로드

  • 한 요청에서 여러 형식을 선택하면 한 번만 과금
  • 같은 곡을 다시 제출하면 같은 형식이어도 새로 과금
  • 이후 다른 형식을 새 작업으로 요청해도 새로 과금
  • 실패한 다운로드 작업은 자동 환불
이미 받은 파일 URL을 재사용하고 요청 중에는 다운로드 버튼을 비활성화해 중복 제출과 과금을 막으세요.

기존 API에서 이전

기존 API는 임시로 사용할 수 있지만 새 코드는 /generations/download를 사용하세요.

Response

integer
응답 코드, 성공 시 200
array
제출 응답 데이터