Public API

The public API is available at:

https://aistemsplitter.com/api/v1

Create an API key from Settings → Developer. Store the API key and webhook signing secret when they are shown because they are only displayed once.

Authentication

Send your key as a bearer token:

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

Create a Split from a Direct URL

curl -sS -X POST "$BASE_URL/api/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"
  }'

Upload Flow

Reserve an upload:

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

Upload the file to the returned uploadUrl with the returned uploadHeaders, then create the split with input.type set to uploaded_file.

Poll Status

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

Statuses are queued, processing, succeeded, and failed. Successful jobs include non-empty stem URLs.

Webhooks

When webhookUrl is provided, AIStemSplitter posts a terminal event:

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

Verify AIStemSplitter-Signature with the webhook signing secret:

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

The HMAC input is:

<timestamp>.<raw-json-body>

Use SHA-256 HMAC and reject stale timestamps in your receiver.

Credits

One credit equals one second of source audio. GET /credits returns the current balance in seconds.

Error Codes

Code	HTTP	Meaning
`UNAUTHORIZED`	401	Missing or invalid API key
`INSUFFICIENT_CREDITS`	402	Not enough credits
`VALIDATION_ERROR`	422	Invalid request body or audio source
`RATE_LIMITED`	429	API key exceeded its per-minute limit
`SERVER_ERROR`	500	Internal service error