API 레퍼런스

음악

이 엔드포인트의 모델(1)

suno

워크벤치에서 사용해 보기

POST/v1/music/generations

GET/v1/music/tasks/{task_id}

GET/v1/music/tasks/{task_id}/content

노래와 연주곡 워크플로를 위한 비동기 음악 생성입니다. 제출하면 바로 task_id가 반환되며, 작업을 폴링하거나 웹훅 콜백을 받은 뒤 /content에서 완성된 오디오를 읽으세요.

#요청 파라미터

modelstring필수
모델 페이지의 음악 모델 ID(예: suno).
promptstring필수
곡의 내용, 분위기, 악기 구성, 가사 방향을 설명하세요.
titlestring선택
선택 사항인 트랙 제목. 지원하는 모델 계열에 전달됩니다.
tagsstring | array선택
cinematic, pop, ambient 같은 선택적 장르·스타일 힌트.
versionstring선택
제공업체가 여러 세대를 제공할 때 쓰는 모델 계열 버전 전환값.
mvstring선택
제공업체별 음악 모드 선택값. 사용자가 직접 제어해야 하는 경우가 아니면 서버 측에 두세요.
instrumentalboolean선택
모델이 지원하는 경우 보컬 없는 연주곡을 생성합니다.
make_instrumentalboolean선택
연주곡 출력을 위한 또 다른 제공업체 플래그. 일부 제공업체는 instrumental 대신 이것을 사용합니다.
continue_clip_idstring선택
새 트랙을 시작하지 않고 이전 클립을 이어 가거나 연장합니다.
continue_atnumber선택
이어 가기 흐름에서 재개할 지점(초).
webhook_urlstring선택
작업이 최종 상태에 도달하면 호출되는 HTTPS URL.
webhook_secretstring선택
설정하면 전송에 X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret))가 포함됩니다.

간단하게 시작하기

대부분의 제품은 첫 연동에서 prompt만으로 충분합니다. title, tags, version, 이어 가기 관련 필드는 고급 컨트롤이므로 제품에 분명한 필요가 있을 때만 추가하세요.

다른 미디어 작업과 같은 비동기 규약

음악도 이미지·동영상 작업과 같은 제출 → 폴링 또는 웹훅 → /content 패턴을 따르므로, 보통 백엔드 작업 실행기 하나로 세 가지를 모두 처리할 수 있습니다.

#관련 오류

404 not_found알 수 없는 경로나 모델 이름, 또는 만료되었거나 다른 계정의 task_id입니다.
422 unprocessable_entity게이트웨이가 전달한 파라미터 값을 제공업체가 거부했습니다(예: 지원하지 않는 크기나 길이).
401Bearer 토큰이 유효하지 않거나 없습니다. 이 경로에는 error.code가 없으므로 상태 코드로 판단하세요.
402 insufficient_user_quota지갑 잔액이 사전 차감 추정액보다 부족합니다.
429키별 속도 제한입니다. 본문은 비어 있으며 Retry-After만큼 기다리세요. insufficient_user_quota가 포함된 429는 속도 제한이 아니라 일일 지출 한도입니다.
503 model_not_found알 수 없는 모델이거나, 현재 이 모델을 제공하는 정상 채널이 없습니다.

전체 오류 코드 표 →

#요청 예시

# submit
curl https://www.aisplice.store/v1/music/generations \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "prompt": "a warm cinematic piano theme",
    "instrumental": true
  }'

# poll every 5s
curl https://www.aisplice.store/v1/music/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# fetch the finished track
curl -L https://www.aisplice.store/v1/music/tasks/$TASK_ID/content \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -o song.mp3

#응답

response.json

// POST — submit accepted
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/music/tasks/{task_id}
{
  "task_id": "task_xxx",
  "status": "in_progress",
  "progress": "42%"
}

// GET /v1/music/tasks/{task_id}/content
{
  "task_id": "task_xxx",
  "status": "completed",
  "metadata": {
    "audio_url": "https://…",
    "lyric": "…"
  }
}

아직 해결되지 않았나요?

요청 ID나 오류 메시지를 보내 주시면 확인해 드리겠습니다.

이전동영상 다음3D 모델