Séparation de stems, en Python.
Livrez la séparation de stems depuis votre service Python en douze lignes — sans GPU, sans téléchargement de modèle, sans FFmpeg. Client typé sur PyPI, handlers webhook FastAPI et Flask sur cette page, le même modèle htdemucs_ft que vous connaissez déjà.
Installation
Authentification
Créez une clé sur la page des paramètres développeur, puis exportez-la comme AISTEMSPLITTER_API_KEY afin que le client la récupère automatiquement. Passez api_key= au constructeur seulement quand vous avez besoin d’une clé par requête — la variable d’environnement est le défaut recommandé.
import os
from aistemsplitter import AiStemSplitter
client = AiStemSplitter(api_key=os.environ["AISTEMSPLITTER_API_KEY"])Hello world
Douze lignes des imports à quatre stems sur disque. Soumet un job à htdemucs_ft, poll jusqu’à la fin, puis écrit vocals.wav, drums.wav, bass.wav et other.wav à côté de votre script. Copiez, collez, exécutez.
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)Méthodes
La surface complète du SDK tient en quatre méthodes typées que vous pouvez parcourir en moins d’une minute — soumettre, récupérer, attendre, télécharger. Chacune reflète un endpoint REST, afin que vous puissiez descendre au HTTP brut via /developers/api lorsque le wrapper typé ne suffit plus. Modèles exposés : htdemucs_ft, htdemucs, htdemucs_6s. Facturé à 0,08–0,14 $ par minute sur des packs de crédits sans expiration.
Soumet un nouveau job de séparation ; renvoie un job id et le statut queued.
Récupère le statut actuel d’un job de séparation.
Poll jusqu’à ce que le job réussisse, échoue ou que le timeout expire.
Liste paginée des jobs de séparation récents pour la clé API.
Obtient une URL PUT présignée pour les uploads directs navigateur/serveur.
Vérifie la signature HMAC-SHA256 d’un payload webhook entrant.
Webhooks
Évitez la boucle de polling en production. Définissez webhook_url à la soumission, puis vérifiez la signature HMAC sur le POST entrant et lisez les URLs de stems présignées directement depuis le body. Handlers FastAPI et Flask sur la même page.
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.
Dois-je utiliser le client sync ou async ?
Par défaut, utilisez sync (StemSplitter) — c’est ce qu’utilise le hello world en 12 lignes, et c’est ce qui s’intègre naturellement dans une vue Django ou une tâche Celery. Passez à AsyncStemSplitter quand vous êtes déjà sur FastAPI, Starlette ou asyncio dans un notebook : les noms de méthodes correspondent (await client.submit, await client.wait, await client.download), donc l’échange coûte un import + un await par appel.
Fonctionne-t-il avec FastAPI et Flask ?
Oui — les deux sont first-class. La section Webhooks ci-dessus fournit des handlers exécutables pour chacun : FastAPI utilise async def webhook(request: Request) avec verify_signature ; Flask utilise une route sync @app.post. Les deux vérifient HMAC-SHA256 avec un seul import (from aistemsplitter import verify_signature) et dépaquettent les URLs de stems présignées depuis le body JSON sans parsing supplémentaire.
Comment l’installer dans un virtualenv ou un projet Poetry ?
Outillage standard : `python -m venv .venv && source .venv/bin/activate && pip install aistemsplitter` pour venv ; `poetry add aistemsplitter` pour Poetry ; `uv add aistemsplitter` pour uv. Le package est en roues pure-Python (aucune compilation native), donc l’installation se termine en quelques secondes sur toutes les plateformes — pas de shim pyenv, pas d’étape FFmpeg, pas de pilote GPU.
La sortie hébergée correspondra-t-elle à la qualité de mon htdemucs_ft local ?
Oui. Nous exposons le même fichier de modèle que la communauté open source utilise — htdemucs_ft, plus htdemucs et htdemucs_6s — donc la sortie est bit-comparable à une exécution Demucs locale avec le même modèle + la même entrée, modulo nos paramètres d’inférence managée (batch size, précision). Passez model='htdemucs_6s' à la soumission quand vous avez besoin des stems guitar et piano.
Et si je dépasse le SDK typé et que j’ai besoin de HTTP brut ?
Passez directement à /developers/api. Le SDK est un wrapper typé fin au-dessus des mêmes endpoints REST que le quickstart curl appelle, donc le header d’authentification (Authorization: Bearer ast_live_…), le schéma de signature webhook (HMAC-SHA256 dans aistemsplitter-signature) et les formes de réponse sont identiques. Vous pouvez combiner — appeler submit via le SDK, récupérer le statut via httpx brut pour une politique de retry personnalisée.
Comment gérer de l’audio très long sans timeout ?
Deux stratégies. (1) Utilisez les webhooks — définissez webhook_url à la soumission et évitez entièrement la boucle de polling ; l’API poste les résultats quand le job se termine, quelle que soit la durée. (2) Pour les fichiers de plus de 50 MB, appelez client.presign_upload() pour obtenir une URL direct-to-storage, uploadez via httpx multipart, puis soumettez avec audio_url retournée au lieu de streamer via notre gateway.
Étapes suivantes
Livrez la séparation de stems avant la fin du sprint.
Pas de carte pour créer une clé. L’offre gratuite couvre vos 3 premières minutes ; le reste utilise des packs de crédits sans expiration — 0,08–0,14 $ par minute selon le volume.