公開 API | AI Stem Splitter

公開 API は次の URL で利用できます。

txt

https://api.aistemsplitter.org/v1

以下の例では BASE_URL=https://api.aistemsplitter.org を前提にしています。

設定 → 開発者 から APIキーを作成してください。APIキーと webhook 署名シークレットは一度だけ表示されるため、表示された時点で保存してください。

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 署名シークレットで 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	サーバー内部エラー