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 资产

鉴权

使用 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"
  }'

上传流程

先创建上传 reservation：

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。

Credits

1 credit 等于 1 秒源音频。GET /credits 返回当前可用秒数。

错误码

Code	HTTP	含义
`UNAUTHORIZED`	401	API key 缺失或无效
`INSUFFICIENT_CREDITS`	402	credits 不足
`VALIDATION_ERROR`	422	请求体或音频源无效
`RATE_LIMITED`	429	API key 超出每分钟限制
`SERVER_ERROR`	500	服务端错误