curl --request POST \
--url https://api.apimart.ai/v1/music/generations/download \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"]
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/music/generations/download",
headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
json={
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"],
},
)
print(response.json())
const response = await fetch(
"https://api.apimart.ai/v1/music/generations/download",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "suno",
task_id: "task_01JGXXXXXXXXXXXX",
audio_index: 1,
formats: ["mp3", "wav"],
}),
},
);
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01JHXXXXXXXXXXXX"
}
]
}
{
"error": {
"message": "`formats` contains unsupported format `flac`. Supported: mp3 / m4a / wav",
"type": "invalid_request_error",
"code": "invalid_source_reference"
}
}
{
"error": {
"code": 401,
"message": "인증에 실패했습니다. API 키를 확인하세요.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "계정 잔액이 부족합니다",
"type": "payment_required"
}
}
Suno
오디오 파일 다운로드
- Suno 곡을 MP3, M4A 또는 WAV 파일로 다운로드
- 한 요청에서 여러 형식을 선택하고 파일별 URL 수신
- task_id와 audio_index로 원본 곡 선택
- 비동기 제출 후 음악 작업 API로 결과 조회
POST
/
v1
/
music
/
generations
/
download
curl --request POST \
--url https://api.apimart.ai/v1/music/generations/download \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"]
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/music/generations/download",
headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
json={
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"],
},
)
print(response.json())
const response = await fetch(
"https://api.apimart.ai/v1/music/generations/download",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "suno",
task_id: "task_01JGXXXXXXXXXXXX",
audio_index: 1,
formats: ["mp3", "wav"],
}),
},
);
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01JHXXXXXXXXXXXX"
}
]
}
{
"error": {
"message": "`formats` contains unsupported format `flac`. Supported: mp3 / m4a / wav",
"type": "invalid_request_error",
"code": "invalid_source_reference"
}
}
{
"error": {
"code": 401,
"message": "인증에 실패했습니다. API 키를 확인하세요.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "계정 잔액이 부족합니다",
"type": "payment_required"
}
}
기존
POST /v1/music/generations/wav 엔드포인트는 더 이상 권장되지 않습니다. 임시 호환을 위해 계속 사용할 수 있으며 새 API에 formats: ["wav"]를 전달한 것과 같습니다. 새 코드는 POST /v1/music/generations/download를 사용하세요.원본 곡 선택: 원본 오디오를 만든 작업의
task_id를 전달하고 audio_index로 결과 music[]에서 곡을 선택합니다. 인덱스는 1부터 시작하며 기본값은 1입니다.curl --request POST \
--url https://api.apimart.ai/v1/music/generations/download \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"]
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/music/generations/download",
headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
json={
"model": "suno",
"task_id": "task_01JGXXXXXXXXXXXX",
"audio_index": 1,
"formats": ["mp3", "wav"],
},
)
print(response.json())
const response = await fetch(
"https://api.apimart.ai/v1/music/generations/download",
{
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "suno",
task_id: "task_01JGXXXXXXXXXXXX",
audio_index: 1,
formats: ["mp3", "wav"],
}),
},
);
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01JHXXXXXXXXXXXX"
}
]
}
{
"error": {
"message": "`formats` contains unsupported format `flac`. Supported: mp3 / m4a / wav",
"type": "invalid_request_error",
"code": "invalid_source_reference"
}
}
{
"error": {
"code": 401,
"message": "인증에 실패했습니다. API 키를 확인하세요.",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "계정 잔액이 부족합니다",
"type": "payment_required"
}
}
인증
요청 매개변수
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를 사용합니다.GET /v1/music/tasks/{task_id}
completed 또는 failed가 아니면 2초마다 최대 60초 동안 조회하세요.
완료
{
"code": 200,
"data": {
"id": "task_01JHXXXXXXXXXXXX",
"status": "completed",
"progress": 100,
"cost": 0.01,
"credits_cost": 0.1,
"result": {
"music_id": "518c74ee-62ac-4ccd-b3d9-7003acd12ad7",
"files": [
{
"format": "mp3",
"url": "https://assets.apimart.ai/audio/example.mp3"
},
{
"format": "wav",
"url": "https://assets.apimart.ai/audio/example.wav"
}
],
"wavUrl": "https://assets.apimart.ai/audio/example.wav"
}
}
}
result.files[]에서 읽습니다.
| 필드 | 유형 | 설명 |
|---|---|---|
format | string | mp3 / m4a / wav |
url | string | 파일 다운로드 URL |
result.wavUrl은 기존 WAV API 호환용입니다. 새 코드는 항상 result.files[]를 사용하세요.처리 중
{
"code": 200,
"data": {
"id": "task_01JHXXXXXXXXXXXX",
"status": "processing",
"progress": 50,
"created": 1756800000
}
}
result가 없습니다. 계속 조회하세요.
실패
실패한 작업은 자동 환불되고cost: 0을 반환합니다. error.message를 표시하고 다시 시도할 수 있게 하세요.
파일 URL
보통 APIMart 파일 도메인을 반환합니다. 저장 전송이 실패한 경우 유효 기간이 보장되지 않는 업스트림 CDN URL이 반환될 수 있습니다.URL을 받은 후 즉시 다운로드하고 저장하세요. 임시 URL을 장기 저장소처럼 사용하지 마세요.
오류
검증 오류는 작업 생성 및 과금 전에 HTTP 400을 반환합니다.| 오류 텍스트 | 원인 |
|---|---|
formats is required / must contain at least one | 형식 누락 |
unsupported format | mp3 / m4a / wav 외의 값 |
task_id is required / invalid task_id format | 원본 작업 ID 누락 또는 형식 오류 |
source task not found | 원본 작업이 없거나 다른 계정 소유 |
audio_index N out of range | 곡 번호가 범위를 벗어남 |
track #N has no music_id | 원본 작업이 미완료이거나 선택한 곡에 오디오가 없음 |
model_price_not_configured는 suno@download 가격이 설정되지 않았다는 뜻입니다. 플랫폼 지원팀에 문의하세요.
과금과 반복 다운로드
- 한 요청에서 여러 형식을 선택하면 한 번만 과금
- 같은 곡을 다시 제출하면 같은 형식이어도 새로 과금
- 이후 다른 형식을 새 작업으로 요청해도 새로 과금
- 실패한 다운로드 작업은 자동 환불
이미 받은 파일 URL을 재사용하고 요청 중에는 다운로드 버튼을 비활성화해 중복 제출과 과금을 막으세요.
기존 API에서 이전
| 항목 | 기존 | 신규 |
|---|---|---|
| 경로 | /v1/music/generations/wav | /v1/music/generations/download |
| 형식 | WAV만 | MP3 / M4A / WAV, 복수 선택 |
| 매개변수 | — | formats 또는 format |
| 결과 | result.wavUrl | result.files[] |
/generations/download를 사용하세요.
Response
integer
응답 코드, 성공 시 200