기능별
음악
음악은 작업으로 실행됩니다. 프롬프트를 제출한 뒤 다시 조회하거나 콜백을 받으세요. 먼저 프롬프트만으로 시작하세요.
#1. 모델 선택
suno$0.07 / 요청제한 및 상태
이 용도로 사용할 수 있는 온라인 모델이 1개 있습니다. 모델을 바꾸면 아래 코드도 바뀝니다.
#2. 요청 복사
YOUR_API_KEY를 내 키로 바꾼 뒤 실행하세요. 표시된 옵션은 이 모델이 받는 옵션입니다.
https://www.aisplice.store/v1/music/generationsBearer API key비동기 작업옵션이 모델에 공개된 옵션만 표시됩니다.
# Requires curl and jq
API_KEY="${API_KEY:-YOUR_API_KEY}"
# 1. Submit once
SUBMITTED=$(curl --fail-with-body -sS https://www.aisplice.store/v1/music/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: model-docs-$(date +%s)-$$" \\
-d '{
"model": "Suno",
"prompt": "An uplifting electronic track for a product launch",
"operation": "music",
"version": "v6",
"custom": false,
"instrumental": false
}')
TASK_ID=$(printf '%s' "$SUBMITTED" | jq -r '.task_id // .id // empty')
if [ -z "$TASK_ID" ]; then
printf '%s\n' "$SUBMITTED" >&2
exit 1
fi
echo "task_id=$TASK_ID"
# 2. Poll until terminal
while true; do
STATUS_JSON=$(curl --fail-with-body -sS \
"https://www.aisplice.store/v1/music/tasks/$TASK_ID" \
-H "Authorization: Bearer $API_KEY")
STATUS=$(printf '%s' "$STATUS_JSON" | jq -r '.status // empty' | tr '[:upper:]' '[:lower:]')
echo "status=$STATUS"
case "$STATUS" in
completed|succeeded|success) break ;;
failed|failure|cancelled|canceled)
printf '%s\n' "$STATUS_JSON" | jq .
exit 1
;;
esac
sleep 3
done
# 3. Fetch the final result
curl --fail-with-body -sS \
"https://www.aisplice.store/v1/music/tasks/$TASK_ID/content" \
-H "Authorization: Bearer $API_KEY" | jq .모든 파라미터
이 모델이 받는 모든 필드와 허용 값.
모든 파라미터
이 모델이 받는 모든 필드와 허용 값.
prompt원하는 결과를 설명하는 지시문.
응답 흐름
작업 상태, 최종 상태, 결과 응답 예시.
응답 흐름
작업 상태, 최종 상태, 결과 응답 예시.
{
"id": "task_xxx",
"task_id": "task_xxx",
"object": "music.task",
"model": "Suno",
"status": "queued"
}대기 중
queued · submitted · in_progress · processing
성공
completed · succeeded · success
실패
failed · failure · cancelled · canceled
#3. 결과 받기
제출 호출은 바로 task_id로 응답합니다. status가 completed가 될 때까지 몇 초마다 작업을 조회하거나, webhook_url을 넘기면 완료 시 저희가 호출해 드립니다.
GET https://www.aisplice.store/v1/music/tasks/{task_id}
GET https://www.aisplice.store/v1/music/tasks/{task_id}/content
성공했을 때만 과금
#문제가 생겼을 때
- 필드 이름과 함께 400: 이 모델이 받지 않는 옵션입니다. 2단계에 나열된 값을 사용하세요.
- 모델이 콘텐츠를 거부함: 프롬프트를 바꿔 쓰세요. 거부된 요청은 과금되지 않습니다.
- 402: 잔액이 이 요청에 부족합니다. 지갑에서 충전한 뒤 다시 시도하세요.
- 429: 요청 속도를 줄이고 Retry-After 초만큼 기다린 뒤 다시 시도하세요.
- 503 model_not_found: 모델 이름이 틀렸거나 모델이 오프라인입니다. 1단계에서 다시 고르세요.
제품에 통합하기사용자에게 먼저 보여 줄 옵션과 나중에 추가할 옵션.
사용자에게 먼저 보여 줄 옵션프롬프트와 가격에 영향을 주는 옵션 하나로 시작하고, 기본 흐름이 동작하면 나머지를 추가하세요.+
창작 의도
prompt 같은 필드는 사용자가 무엇이 바뀌는지 바로 이해할 수 있으므로 UI에 두어야 합니다.
비용 배수 항목
duration, resolution, size, count 같은 필드는 가격을 명확히 설명할 수 있을 때만 도입하세요.
모드 전환 항목
image, mask, 후속 작업 ID 같은 필드는 워크플로 자체를 바꾸므로 전용 모드에서만 보여야 합니다.
시스템 연동 항목
webhook_secret 같은 필드는 일반 크리에이터가 아닌 연동 개발자를 위한 것이므로 기본 UI에서 빼 두세요.
prompt- 노출 시점
- 항상 노출합니다. 음악 생성에 필요한 최소한의 입력입니다.
- 권장 기본값
- UI에서 필수.
- 중요한 이유
- 주제, 장르, 감정의 방향을 담습니다.
instrumental / make_instrumental- 노출 시점
- 제품이 보컬과 연주곡 출력을 명확히 구분할 때 노출합니다.
- 권장 기본값
- 사용자가 보컬 트랙과 연주곡 중에서 고르는 경우가 아니라면 서버 측에 둡니다.
- 중요한 이유
- 출력 유형을 바꾸므로 명확한 비즈니스 선택과 연결되어야 합니다.
title / tags- 노출 시점
- 사용자가 프롬프트만으로 생성하는 방식을 충분히 이해한 뒤에만 노출합니다.
- 권장 기본값
- 선택적 고급 필드.
- 중요한 이유
- 스타일 제어에 도움이 되지만 첫 성공을 가로막아서는 안 됩니다.
version / mv- 노출 시점
- 사용자가 모델 계열이나 생성 모드를 반드시 골라야 할 때만 노출합니다.
- 권장 기본값
- 서버에서 권장 버전 하나로 고정합니다.
- 중요한 이유
- 결정 피로를 늘리며 보통 운영자용 컨트롤에 속합니다.
continue_clip_id / continue_at- 노출 시점
- 이어 가기나 연장 워크플로에서만 노출합니다.
- 권장 기본값
- 일반 생성 흐름에서는 숨깁니다.
- 중요한 이유
- 전문가용 컨트롤이라 너무 일찍 보여 주면 처음 사용하는 사용자가 혼란스러워합니다.
Phase 1
- prompt
- one size or one duration default
- submit -> poll -> content
Phase 2
- one quality or resolution selector
- clear pricing hint
Phase 3
- advanced controls such as reference media, continuation, webhook, or vendor-specific tuning결과의 기준은 하나로 유지
아직 해결되지 않았나요?
요청 ID나 오류 메시지를 보내 주시면 확인해 드리겠습니다.