공개 API | AI Stem Splitter

공개 API는 다음 URL에서 사용할 수 있습니다.

txt

https://api.aistemsplitter.org/v1

아래 예시는 BASE_URL=https://api.aistemsplitter.org 를 기준으로 합니다.

설정 → 개발자에서 API 키를 생성하세요. API 키와 webhook 서명 secret은 한 번만 표시되므로 표시되는 즉시 저장해야 합니다.

API 자산

인증

키를 bearer token으로 전송합니다.

txt

curl -sS "$BASE_URL/v1/credits" \
  -H "Authorization: Bearer $AISTEMSPLITTER_API_KEY"

Direct URL로 분리 작업 생성

txt

curl -sS -X POST "$BASE_URL/v1/audio/splits" \
  -H "Authorization: Bearer $AISTEMSPLITTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-001" \
  -d '{
    "input": {
      "type": "direct_url",
      "url": "https://example.com/song.mp3"
    },
    "stemModel": "6s",
    "webhookUrl": "https://example.com/webhooks/aistemsplitter"
  }'

업로드 흐름

먼저 업로드를 예약합니다.

txt

curl -sS -X POST "$BASE_URL/v1/audio/uploads" \
  -H "Authorization: Bearer $AISTEMSPLITTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "song.wav",
    "contentType": "audio/wav",
    "contentLength": 23812033
  }'

반환된 uploadUrl 에 반환된 uploadHeaders 를 붙여 파일을 업로드한 다음, input.type 을 uploaded_file 로 설정해 분리 작업을 생성합니다.

상태 조회

txt

curl -sS "$BASE_URL/v1/audio/splits/$SPLIT_ID" \
  -H "Authorization: Bearer $AISTEMSPLITTER_API_KEY"

상태는 queued, processing, succeeded, failed 입니다. 성공한 작업에는 비어 있지 않은 stem URL이 포함됩니다.

Webhooks

webhookUrl 이 제공되면 AIStemSplitter가 최종 이벤트를 전송합니다.

txt

{
  "event": "audio.split.completed",
  "data": {
    "id": "split_123",
    "status": "succeeded"
  }
}

webhook 서명 secret으로 AIStemSplitter-Signature 를 검증하세요.

txt

AIStemSplitter-Signature: t=1760000000,v1=<hex-hmac>

HMAC 입력은 다음 형식입니다.

txt

<timestamp>.<raw-json-body>

수신 측에서는 SHA-256 HMAC을 사용하고 오래된 timestamp는 거부해야 합니다.

크레딧

1크레딧은 원본 오디오 1초와 같습니다. GET /credits 는 현재 잔액을 초 단위로 반환합니다.

오류 코드

Code	HTTP	의미
`UNAUTHORIZED`	401	API 키가 없거나 유효하지 않음
`INSUFFICIENT_CREDITS`	402	크레딧 부족
`VALIDATION_ERROR`	422	요청 본문 또는 오디오 소스가 유효하지 않음
`RATE_LIMITED`	429	API 키가 분당 제한을 초과함
`SERVER_ERROR`	500	내부 서비스 오류