安裝
驗證
在 developer settings 頁面建立一把 key，然後 export 為 AISTEMSPLITTER_API_KEY，讓 client 自動讀取。只有當你需要每次 request 使用不同 key 時，才在 constructor 傳 api_key=——預設建議使用 env var。
import os
from aistemsplitter import AiStemSplitter
client = AiStemSplitter(api_key=os.environ["AISTEMSPLITTER_API_KEY"])Hello world
從 imports 到磁碟上的 4 條 stem，只要 12 行。提交一個 job 到 htdemucs_ft，輪詢到完成，然後把 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)Methods
完整 SDK surface 只有 4 個型別化 methods，1 分鐘內就能看完——submit、get、wait、download。每個 method 都映射一個 REST endpoint，所以當 typed wrapper 不夠用時，可以隨時切到 /developers/api 的 raw HTTP。暴露的模型：htdemucs_ft、htdemucs、htdemucs_6s。依輸入分鐘從永不到期的分鐘包扣費，每分鐘 $0.08–$0.14。
提交新的 split job；回傳 job id 和 queued status。
取得某個 split job 的目前狀態。
持續輪詢，直到 job 成功、失敗或超時。
依頁列出這把 API 金鑰最近的 split jobs。
取得 pre-signed PUT URL，用於瀏覽器/伺服器直接上傳。
驗證傳入 webhook payload 上的 HMAC-SHA256 signature。
Webhooks
在 production 跳過輪詢迴圈。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 加每次呼叫一個 await。
它能搭配 FastAPI 和 Flask 使用嗎？
可以——兩者都是 first-class。上方 Webhooks 區塊為每個框架提供可執行 handler：FastAPI 使用 async def webhook(request: Request) 搭配 verify_signature；Flask 使用 sync @app.post route。兩者都透過一個 import（from aistemsplitter import verify_signature）驗證 HMAC-SHA256，並從 JSON body 解出 presigned stem URLs，不需額外解析。
如何安裝到 virtualenv 或 Poetry project？
使用標準工具即可：venv 用 `python -m venv .venv && source .venv/bin/activate && pip install aistemsplitter`；Poetry 用 `poetry add aistemsplitter`；uv 用 `uv add aistemsplitter`。這個 package 是 pure-Python wheels（不需 native compilation），所以每個平台上都能幾秒完成安裝——不需要 pyenv shim、不需要 FFmpeg 預步驟，也不需要 GPU driver。
託管輸出會和我本機 htdemucs_ft 的品質一致嗎？
會。我們暴露的是開源社群信任的同一個模型檔——htdemucs_ft，以及 htdemucs 和 htdemucs_6s——所以在相同模型和相同輸入下，輸出可以與本機 Demucs 執行結果做 bit-comparable 對比，差異只來自我們的 managed inference settings（batch size、precision）。當你需要 guitar 和 piano stems 時，在 submit 傳 model='htdemucs_6s'。
如果 typed SDK 不夠用、需要 raw HTTP 怎麼辦？
直接切到 /developers/api。SDK 只是同一套 REST endpoints 上的 thin typed wrapper，也就是 curl quickstart 呼叫的同一套介面，所以 auth header（Authorization: Bearer ast_live_…）、webhook signature scheme（aistemsplitter-signature 中的 HMAC-SHA256）和 response shapes 都完全一致。你可以混用——用 SDK submit，用 raw httpx fetch status 來實作自訂 retry policy。
如何處理很長的音訊，避免 timeout？
兩種策略。1）使用 webhooks——submit 時設定 webhook_url，完全跳過輪詢迴圈；不論時長多久，API 都會在 job 完成後 POST 結果。2）對於大於 50 MB 的檔案，呼叫 client.presign_upload() 取得 direct-to-storage URL，透過 httpx multipart 上傳，然後用回傳的 audio_url submit，而不是把檔案串流經過我們的 gateway。