Stems splitsen, in Python.
Ship stemscheiding vanuit je Python-service in twaalf regels — geen GPU, geen modeldownload, geen FFmpeg. Typed client op PyPI, FastAPI- en Flask-webhookhandlers op deze pagina, hetzelfde htdemucs_ft-model dat je al vertrouwt.
Installeren
Authenticeren
Maak een sleutel op de developer settings-pagina en exporteer die daarna als AISTEMSPLITTER_API_KEY, zodat de client hem automatisch oppakt. Geef api_key= alleen door aan de constructor wanneer je per request een sleutel nodig hebt — de env var is de aanbevolen default.
import os
from aistemsplitter import AiStemSplitter
client = AiStemSplitter(api_key=os.environ["AISTEMSPLITTER_API_KEY"])Hello world
Twaalf regels van imports tot vier stems op disk. Dient een job in bij htdemucs_ft, pollt tot die klaar is en schrijft daarna vocals.wav, drums.wav, bass.wav en other.wav naast je script. Kopieer, plak, draai.
import os
import requests
from aistemsplitter import AiStemSplitter
client = AiStemSplitter(api_key=os.environ["AISTEMSPLITTER_API_KEY"])
# 1. Submit a split job
job = client.create_split(
input={"type": "direct_url", "url": "https://example.com/song.mp3"},
stem_model="htdemucs_ft",
)
# 2. Wait until completion (polls under the hood)
result = client.wait_for_split(job.id)
# 3. Download all six stems to disk
for name, url in result.stems.items():
with requests.get(url, stream=True) as r:
with open(f"./{name}.wav", "wb") as f:
for chunk in r.iter_content(chunk_size=8192):
f.write(chunk)Methoden
Het volledige SDK-oppervlak bestaat uit vier typed methods die je in minder dan een minuut scant — submit, get, wait, download. Elke methode spiegelt één REST-endpoint, zodat je naar raw HTTP via /developers/api kunt afdalen zodra je de typed wrapper ontgroeit. Beschikbare modellen: htdemucs_ft, htdemucs, htdemucs_6s. Gefactureerd tegen $0.08–$0.14 per minuut tegen creditpakketten die nooit verlopen.
Dien een nieuwe split-job in; retourneert een job-id en queued-status.
Haal de huidige status van een split-job op.
Poll totdat de job slaagt, faalt of de timeout verstrijkt.
Gepagineerde lijst met recente split-jobs voor de API-sleutel.
Krijg een vooraf ondertekende PUT-URL voor directe browser-/serveruploads.
Verifieer de HMAC-SHA256-signature op een inkomende webhook-payload.
Webhooks
Sla de polling-loop in productie over. Zet webhook_url op submit, verifieer daarna de HMAC-signature op de inkomende POST en lees presigned stem-URL's rechtstreeks uit de body. FastAPI- en Flask-handlers op dezelfde pagina.
import os
from fastapi import FastAPI, Request, HTTPException
from aistemsplitter import AiStemSplitter
app = FastAPI()
client = AiStemSplitter(api_key=os.environ["AISTEMSPLITTER_API_KEY"])
@app.post("/webhooks/aistemsplitter")
async def handle_webhook(request: Request):
raw = await request.body()
try:
event = client.verify_webhook(request.headers, raw)
except Exception:
raise HTTPException(status_code=400, detail="invalid signature")
if event.type == "split.succeeded":
# event.data["stems"] -> six URLs
pass
elif event.type == "split.failed":
# event.data["error"] -> { code, message }
pass
return {"ok": True}FAQ
Should I use the sync client or the async one?
Default to sync (StemSplitter) — that's what the 12-line hello world uses, and it's what fits naturally inside a Django view or a Celery task. Switch to AsyncStemSplitter when you're already on FastAPI, Starlette, or asyncio in a notebook: the method names match (await client.submit, await client.wait, await client.download), so swapping costs one import + one await per call.
Does it work with FastAPI and Flask?
Yes — both are first-class. The Webhooks section above ships runnable handlers for each: FastAPI uses async def webhook(request: Request) with verify_signature; Flask uses a sync @app.post route. Both verify HMAC-SHA256 with one import (from aistemsplitter import verify_signature) and unpack presigned stem URLs from the JSON body without extra parsing.
How do I install in a virtualenv or Poetry project?
Standard tooling: `python -m venv .venv && source .venv/bin/activate && pip install aistemsplitter` for venv; `poetry add aistemsplitter` for Poetry; `uv add aistemsplitter` for uv. The package is pure-Python wheels (no native compilation), so installation completes in seconds on every platform — no pyenv shim, no FFmpeg pre-step, no GPU driver.
Will hosted output match my local htdemucs_ft quality?
Yes. We expose the same model file the open-source community trusts — htdemucs_ft, plus htdemucs and htdemucs_6s — so output is bit-comparable to a local Demucs run with the same model + same input, modulo our managed inference settings (batch size, precision). Pass model='htdemucs_6s' on submit when you need guitar and piano stems.
What if I outgrow the typed SDK and need raw HTTP?
Drop straight to /developers/api. The SDK is a thin typed wrapper over the same REST endpoints the curl quickstart calls, so the auth header (Authorization: Bearer ast_live_…), the webhook signature scheme (HMAC-SHA256 in aistemsplitter-signature), and the response shapes are identical. You can mix-and-match — call submit via the SDK, fetch status via raw httpx for a custom retry policy.
How do I handle very long audio without timing out?
Two strategies. (1) Use webhooks — set webhook_url on submit and skip the polling loop entirely; the API posts results when the job finishes regardless of duration. (2) For files larger than 50 MB, call client.presign_upload() to get a direct-to-storage URL, upload via httpx multipart, then submit with the returned audio_url instead of streaming through our gateway.
Moet ik de sync client of de async client gebruiken?
Gebruik standaard sync (StemSplitter) — dat is wat de 12-regelige hello world gebruikt, en het past natuurlijk in een Django view of Celery task. Stap over op AsyncStemSplitter wanneer je al op FastAPI, Starlette of asyncio in een notebook zit: de methodenamen blijven gelijk (await client.submit, await client.wait, await client.download), dus wisselen kost één import + één await per call.
Werkt het met FastAPI en Flask?
Ja — beide zijn first-class. De Webhooks-sectie hierboven levert runnable handlers voor beide: FastAPI gebruikt async def webhook(request: Request) met verify_signature; Flask gebruikt een sync @app.post-route. Beide verifiëren HMAC-SHA256 met één import (from aistemsplitter import verify_signature) en pakken presigned stem-URL's uit de JSON-body zonder extra parsing.
Hoe installeer ik in een virtualenv- of Poetry-project?
Standaard tooling: `python -m venv .venv && source .venv/bin/activate && pip install aistemsplitter` voor venv; `poetry add aistemsplitter` voor Poetry; `uv add aistemsplitter` voor uv. Het package bestaat uit pure-Python wheels (geen native compilation), dus installatie is op elk platform in seconden klaar — geen pyenv-shim, geen FFmpeg-voorstap, geen GPU-driver.
Komt hosted output overeen met mijn lokale htdemucs_ft-kwaliteit?
Ja. We exposen hetzelfde modelbestand dat de open-source community vertrouwt — htdemucs_ft, plus htdemucs en htdemucs_6s — zodat output op bitniveau vergelijkbaar is met een lokale Demucs-run met hetzelfde model + dezelfde input, afgezien van onze managed inference-instellingen (batch size, precision). Geef model='htdemucs_6s' mee op submit wanneer je guitar- en piano-stems nodig hebt.
Wat als ik de typed SDK ontgroei en raw HTTP nodig heb?
Ga direct naar /developers/api. De SDK is een dunne typed wrapper over dezelfde REST-endpoints die de curl-quickstart aanroept, dus de auth header (Authorization: Bearer ast_live_…), de webhook-signature scheme (HMAC-SHA256 in aistemsplitter-signature) en de response shapes zijn identiek. Je kunt mixen en matchen — submit via de SDK aanroepen, status ophalen via raw httpx voor een eigen retry-policy.
Hoe verwerk ik heel lange audio zonder timeouts?
Twee strategieën. (1) Gebruik webhooks — zet webhook_url op submit en sla de polling-loop volledig over; de API post resultaten wanneer de job klaar is, ongeacht de duur. (2) Roep voor bestanden groter dan 50 MB client.presign_upload() aan om een direct-to-storage URL te krijgen, upload via httpx multipart en submit daarna met de geretourneerde audio_url in plaats van door onze gateway te streamen.
Volgende stappen
Ship stemscheiding vóór de sprint eindigt.
Geen kaart nodig om een sleutel te maken. De gratis tier dekt je eerste 3 minuten; daarna draai je op creditpakketten die nooit verlopen — $0.08–$0.14 per minuut, afhankelijk van volume.