Public API | AI Stem Splitter

Public API 位於：

txt

https://api.aistemsplitter.org/v1

以下範例假設 BASE_URL=https://api.aistemsplitter.org。

請在 設定 → 開發者 建立 API key。API key 和 webhook 簽名密鑰只會顯示一次，請在顯示時立即保存。

API 資產

驗證

將你的 key 作為 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
  }'

將檔案帶著回傳的 uploadHeaders 上傳到回傳的 uploadUrl，接著以 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。

Credits

1 credit 等於 1 秒來源音訊。GET /credits 會以秒數回傳目前餘額。

錯誤碼

Code	HTTP	含義
`UNAUTHORIZED`	401	API key 缺失或無效
`INSUFFICIENT_CREDITS`	402	credits 不足
`VALIDATION_ERROR`	422	請求 body 或音訊來源無效
`RATE_LIMITED`	429	API key 超出每分鐘限制
`SERVER_ERROR`	500	服務端內部錯誤