설치
인증
developer settings 페이지에서 키를 발급한 뒤 AISTEMSPLITTER_API_KEY로 export하면 client가 자동으로 읽습니다. 요청마다 다른 키가 필요할 때만 constructor에 api_key=를 전달하세요. env var가 권장 기본값입니다.
import os
from aistemsplitter import AiStemSplitter
client = AiStemSplitter(api_key=os.environ["AISTEMSPLITTER_API_KEY"])Hello world
imports부터 디스크의 4개 스템까지 12줄입니다. htdemucs_ft에 job을 제출하고 완료될 때까지 폴링한 뒤, vocals.wav, drums.wav, bass.wav, other.wav를 스크립트 옆에 씁니다. 복사하고, 붙여 넣고, 실행하세요.
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)메서드
전체 SDK surface는 1분 안에 훑어볼 수 있는 4개의 typed methods입니다 — submit, get, wait, download. 각 메서드는 하나의 REST endpoint를 그대로 반영하므로 typed wrapper를 넘어설 때마다 /developers/api를 통해 raw HTTP로 내려갈 수 있습니다. 노출된 models: htdemucs_ft, htdemucs, htdemucs_6s. 만료되지 않는 크레딧 팩에서 분당 $0.08~$0.14로 과금됩니다.
새 split job을 제출하고 job id와 queued status를 반환합니다.
split job의 현재 status를 가져옵니다.
job이 성공, 실패하거나 timeout이 지날 때까지 폴링합니다.
API 키의 최근 split jobs를 paginated list로 반환합니다.
직접 browser/server uploads를 위한 pre-signed PUT URL을 받습니다.
수신 webhook payload의 HMAC-SHA256 signature를 검증합니다.
Webhooks
production에서는 polling loop를 건너뛰세요. submit에 webhook_url을 설정한 뒤, 들어오는 POST의 HMAC signature를 검증하고 body에서 presigned stem URLs를 바로 읽으세요. FastAPI와 Flask handlers가 같은 페이지에 있습니다.
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.
sync client와 async client 중 어느 것을 써야 하나요?
기본은 sync(StemSplitter)를 사용하세요. 12줄 hello world가 사용하는 방식이고, Django view나 Celery task 안에 자연스럽게 맞습니다. 이미 FastAPI, Starlette, notebook의 asyncio 위에 있다면 AsyncStemSplitter로 전환하세요. method names는 동일합니다(await client.submit, await client.wait, await client.download). 바꾸는 비용은 import 하나와 call마다 await 하나입니다.
FastAPI와 Flask에서 동작하나요?
네. 둘 다 first-class입니다. 위 Webhooks 섹션에는 각각 실행 가능한 handlers가 포함되어 있습니다. FastAPI는 verify_signature와 함께 async def webhook(request: Request)를 사용하고, Flask는 sync @app.post route를 사용합니다. 둘 다 한 번의 import(from aistemsplitter import verify_signature)로 HMAC-SHA256을 검증하고, 추가 parsing 없이 JSON body에서 presigned stem URLs를 풉니다.
virtualenv나 Poetry 프로젝트에는 어떻게 설치하나요?
표준 도구를 사용하세요. venv는 `python -m venv .venv && source .venv/bin/activate && pip install aistemsplitter`, Poetry는 `poetry add aistemsplitter`, uv는 `uv add aistemsplitter`입니다. 패키지는 pure-Python wheels(no native compilation)이므로 모든 플랫폼에서 몇 초 안에 설치됩니다. pyenv shim, FFmpeg pre-step, GPU driver가 필요 없습니다.
hosted output이 로컬 htdemucs_ft 품질과 일치하나요?
네. 오픈소스 커뮤니티가 신뢰하는 동일한 모델 파일인 htdemucs_ft와 htdemucs, htdemucs_6s를 노출합니다. 따라서 같은 model + 같은 input으로 로컬 Demucs를 실행한 결과와 bit-comparable합니다. 차이는 관리형 inference settings(batch size, precision) 정도입니다. guitar와 piano stems가 필요하면 submit에서 model='htdemucs_6s'를 전달하세요.
typed SDK를 넘어 raw HTTP가 필요하면 어떻게 하나요?
/developers/api로 바로 내려가세요. SDK는 curl quickstart가 호출하는 동일한 REST endpoints 위의 얇은 typed wrapper입니다. 따라서 auth header(Authorization: Bearer ast_live_…), webhook signature scheme(HMAC-SHA256 in aistemsplitter-signature), response shapes가 동일합니다. 섞어서 사용할 수도 있습니다. 예를 들어 submit은 SDK로 호출하고, custom retry policy를 위해 status fetch는 raw httpx로 호출하세요.
매우 긴 오디오가 timeout되지 않게 하려면 어떻게 하나요?
두 가지 전략이 있습니다. (1) webhooks를 사용하세요. submit에 webhook_url을 설정하고 polling loop를 완전히 건너뛰면, API가 duration과 관계없이 job 완료 시 결과를 POST합니다. (2) 50 MB보다 큰 파일은 client.presign_upload()를 호출해 direct-to-storage URL을 받고, httpx multipart로 업로드한 뒤 gateway로 streaming하지 말고 반환된 audio_url로 submit하세요.