Python SDK

~10 min

Separate audio stems from Python using stemsplit-python

PyPI: stemsplit-python GitHub sourcev0.2.0

Prerequisites

Python 3.8 or newer
StemSplit account with API key
Credit balance for processing

Install

Install the package from PyPI using pip.

pip install stemsplit-python

The only runtime dependency is requests, which is installed automatically.

Quick Start

Create a client, submit an audio URL, and retrieve the separated stem URLs.

Quick start

from stemsplit import StemSplitClient

client = StemSplitClient(api_key="sk_live_xxx")

# Separate stems from a public audio URL
job = client.create_job(
    source_url="https://example.com/song.mp3",
    output_type="BOTH",
    quality="BEST",
)

# Poll every 5 s until complete (raises on failure)
result = client.wait_for_job(job["id"])

print(result["outputs"]["vocals"]["url"])
print(result["outputs"]["instrumental"]["url"])

Response

{
  "id": "job_abc123",
  "status": "COMPLETED",
  "outputs": {
    "vocals": {
      "url": "https://cdn.stemsplit.io/outputs/job_abc123/vocals.mp3",
      "expiresAt": "2026-05-26T00:00:00Z"
    },
    "instrumental": {
      "url": "https://cdn.stemsplit.io/outputs/job_abc123/instrumental.mp3",
      "expiresAt": "2026-05-26T00:00:00Z"
    }
  }
}

Output URLs expire after 1 hour. Download the files promptly or store the URLs and refresh them via the jobs API.

Upload a Local File

Use client.upload_file() to get a presigned upload key, then pass it to create_job().

Upload and separate a local file

from stemsplit import StemSplitClient

client = StemSplitClient(api_key="sk_live_xxx")

# Upload returns an upload key for use in create_job
upload_key = client.upload_file("/path/to/song.mp3")

job = client.create_job(
    upload_key=upload_key,
    output_type="FOUR_STEMS",
    quality="BALANCED",
)

result = client.wait_for_job(job["id"])

for stem, data in result["outputs"].items():
    print(f"{stem}: {data['url']}")

Polling vs Callbacks

The SDK provides two patterns for handling async jobs.

wait_for_job() — built-in polling helperRecommended

Polling helper

# Polls every 5 s by default; raises StemSplitError on failure
result = client.wait_for_job(
    job_id=job["id"],
    poll_interval=5,   # seconds between polls
    timeout=600,       # max wait in seconds (default: 600)
)

Manual polling — full control

Manual polling loop

import time

job_id = job["id"]

while True:
    status = client.get_job(job_id)
    if status["status"] == "COMPLETED":
        print(status["outputs"]["vocals"]["url"])
        break
    if status["status"] == "FAILED":
        raise RuntimeError(status.get("errorMessage", "Job failed"))
    time.sleep(5)

YouTube Jobs

Pass a YouTube URL directly — no downloading required.

Separate stems from a YouTube video

from stemsplit import StemSplitClient

client = StemSplitClient(api_key="sk_live_xxx")

job = client.create_youtube_job(
    youtube_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    output_type="VOCALS",
    quality="BEST",
)

result = client.wait_for_job(job["id"])
print(result["outputs"]["vocals"]["url"])

Output Types & Quality

output_type	Stems returned
`VOCALS`	Isolated vocals track only
`INSTRUMENTAL`	Backing track (vocals removed)
`BOTH`	Vocals + instrumental
`FOUR_STEMS`	Vocals, drums, bass, other
`SIX_STEMS`	Vocals, drums, bass, guitar, piano, other

quality	Speed	Notes
`FAST`	~20 s/min	Good for drafts
`BALANCED`	~40 s/min	Recommended default
`BEST`	~60 s/min	Required for SIX_STEMS

Requirements

Python	3.8 or newer
Dependency	requests
Install	pip install stemsplit-python
Version	0.2.0

Tips

• Store your API key in an environment variable (e.g. STEMSPLIT_API_KEY) and pass via os.environ
• Output download URLs expire after 1 hour — save the files immediately if you need them long-term
• Maximum file size is 50 MB; maximum duration is 60 minutes
• Use SIX_STEMS with BEST quality for guitar, piano and other isolation

Full API Docs

Complete endpoint reference

CLI Guide

Use StemSplit from the terminal