Stem Splitting in Python.
Shippen Sie Stem Separation aus Ihrem Python-Service in zwölf Zeilen — keine GPU, kein Modell-Download, kein FFmpeg. Typisierter Client auf PyPI, FastAPI- und Flask-Webhook-Handler auf dieser Seite, dasselbe htdemucs_ft-Modell, dem Sie bereits vertrauen.
Installieren
Authentifizieren
Erstellen Sie einen Key auf der Entwickler-Einstellungsseite und exportieren Sie ihn dann als AISTEMSPLITTER_API_KEY, damit der Client ihn automatisch aufnimmt. Übergeben Sie api_key= nur dann an den Konstruktor, wenn Sie einen Key pro Request benötigen — env var ist der empfohlene Standard.
import os
from aistemsplitter import AiStemSplitter
client = AiStemSplitter(api_key=os.environ["AISTEMSPLITTER_API_KEY"])Hello World
Zwölf Zeilen von Imports bis zu vier Stems auf der Festplatte. Reicht einen Job an htdemucs_ft ein, pollt bis zur Fertigstellung und schreibt dann vocals.wav, drums.wav, bass.wav und other.wav neben Ihr Skript. Kopieren, einfügen, ausführen.
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
Die gesamte SDK-Oberfläche besteht aus vier typisierten Methoden, die Sie in unter einer Minute erfassen können — submit, get, wait, download. Jede spiegelt einen REST-Endpunkt, sodass Sie jederzeit über /developers/api auf Raw HTTP wechseln können, wenn Sie dem typisierten Wrapper entwachsen. Exponierte Modelle: htdemucs_ft, htdemucs, htdemucs_6s. Abgerechnet mit $0.08–$0.14 pro Minute gegen Credit-Pakete, die nie verfallen.
Reicht einen neuen Split-Job ein; gibt eine Job-ID und queued-Status zurück.
Ruft den aktuellen Status eines Split-Jobs ab.
Pollt, bis der Job erfolgreich ist, fehlschlägt oder das Timeout abläuft.
Paginierte Liste der letzten Split-Jobs für den API-Key.
Erstellt eine vorab signierte PUT-URL für direkte Browser-/Server-Uploads.
Verifiziert die HMAC-SHA256-Signatur eines eingehenden Webhook-Payloads.
Webhooks
Überspringen Sie die Polling-Schleife in Produktion. Setzen Sie webhook_url beim Submit, verifizieren Sie dann die HMAC-Signatur des eingehenden POST und lesen Sie vorab signierte Stem-URLs direkt aus dem Body. FastAPI- und Flask-Handler stehen auf derselben Seite.
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.
Sollte ich den Sync-Client oder den Async-Client nutzen?
Nutzen Sie standardmäßig sync (StemSplitter) — das verwendet auch das 12-Zeilen-Hello-World, und es passt natürlich in eine Django View oder einen Celery Task. Wechseln Sie zu AsyncStemSplitter, wenn Sie bereits auf FastAPI, Starlette oder asyncio in einem Notebook sind: Die Methodennamen stimmen überein (await client.submit, await client.wait, await client.download), sodass der Wechsel einen Import und ein await pro Aufruf kostet.
Funktioniert es mit FastAPI und Flask?
Ja — beide sind first-class. Der Webhooks-Abschnitt oben liefert ausführbare Handler für beide: FastAPI nutzt async def webhook(request: Request) mit verify_signature; Flask nutzt eine synchrone @app.post-Route. Beide verifizieren HMAC-SHA256 mit einem Import (from aistemsplitter import verify_signature) und entpacken vorab signierte Stem-URLs aus dem JSON-Body ohne zusätzliches Parsing.
Wie installiere ich in einem virtualenv- oder Poetry-Projekt?
Standard-Tooling: `python -m venv .venv && source .venv/bin/activate && pip install aistemsplitter` für venv; `poetry add aistemsplitter` für Poetry; `uv add aistemsplitter` für uv. Das Paket besteht aus Pure-Python-Wheels (keine native Kompilierung), daher ist die Installation auf jeder Plattform in Sekunden abgeschlossen — kein pyenv-Shim, kein FFmpeg-Vorschritt, kein GPU-Treiber.
Entspricht gehostete Ausgabe meiner lokalen htdemucs_ft-Qualität?
Ja. Wir exponieren dieselbe Modelldatei, der die Open-Source-Community vertraut — htdemucs_ft plus htdemucs und htdemucs_6s — sodass die Ausgabe mit einem lokalen Demucs-Lauf bei gleichem Modell und gleicher Eingabe bit-vergleichbar ist, abgesehen von unseren verwalteten Inferenz-Einstellungen (Batch Size, Precision). Übergeben Sie model='htdemucs_6s' beim Submit, wenn Sie Gitarren- und Piano-Stems benötigen.
Was, wenn ich dem typisierten SDK entwachse und Raw HTTP brauche?
Wechseln Sie direkt zu /developers/api. Das SDK ist ein dünner typisierter Wrapper über dieselben REST-Endpunkte, die der curl-Quickstart aufruft, sodass der Auth-Header (Authorization: Bearer ast_live_…), das Webhook-Signaturschema (HMAC-SHA256 in aistemsplitter-signature) und die Response-Shapes identisch sind. Sie können mischen — Submit über das SDK aufrufen, Status über Raw httpx für eine eigene Retry-Policy abrufen.
Wie gehe ich mit sehr langem Audio um, ohne in Timeouts zu laufen?
Zwei Strategien. (1) Nutzen Sie Webhooks — setzen Sie webhook_url beim Submit und überspringen Sie die Polling-Schleife vollständig; die API postet Ergebnisse, wenn der Job fertig ist, unabhängig von der Dauer. (2) Für Dateien größer als 50 MB rufen Sie client.presign_upload() auf, um eine Direct-to-Storage-URL zu erhalten, laden per httpx multipart hoch und submitten anschließend mit der zurückgegebenen audio_url, statt durch unser Gateway zu streamen.
Nächste Schritte
Shippen Sie Stem Separation vor Sprint-Ende.
Keine Karte nötig, um einen Key zu erstellen. Der Free Tier deckt Ihre ersten 3 Minuten ab; der Rest läuft über Credit-Pakete, die nie verfallen — $0.08–$0.14 pro Minute je nach Volumen.