Разделение на стемы на Python.
Подключите разделение на стемы к вашему Python-сервису всего за двенадцать строк — без GPU, без загрузки моделей, без FFmpeg. Типизированный клиент в PyPI, обработчики вебхуков для FastAPI и Flask на этой же странице, та же привычная модель htdemucs_ft.
Установка
Аутентификация
Создайте ключ на странице настроек для разработчиков и экспортируйте его в переменную AISTEMSPLITTER_API_KEY — клиент подхватит её автоматически. Передавайте api_key= в конструктор только тогда, когда нужен отдельный ключ на каждый запрос: переменная окружения — рекомендуемый вариант по умолчанию.
import os
from aistemsplitter import AiStemSplitter
client = AiStemSplitter(api_key=os.environ["AISTEMSPLITTER_API_KEY"])Hello world
Двенадцать строк — от импортов до четырёх стемов на диске. Скрипт отправляет задачу в 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)Методы
Весь публичный интерфейс SDK — четыре типизированных метода, которые можно просмотреть меньше чем за минуту: submit, get, wait, download. Каждый из них зеркалит один REST-эндпоинт, поэтому в любой момент можно перейти на сырой HTTP через /developers/api, когда типизированной обёртки станет мало. Доступные модели: htdemucs_ft, htdemucs, htdemucs_6s. Оплата — 0,08–0,14 $ за минуту по пакетам кредитов, которые не сгорают.
Отправляет новую задачу разделения; возвращает идентификатор задачи и статус queued.
Получает текущий статус задачи разделения.
Опрашивает задачу до её успешного завершения, ошибки или истечения тайм-аута.
Постраничный список недавних задач разделения для данного API-ключа.
Возвращает предподписанный PUT-URL для прямой загрузки из браузера или сервера.
Проверяет подпись HMAC-SHA256 на входящем теле вебхука.
Вебхуки
Откажитесь от цикла опроса в продакшене. Укажите webhook_url при отправке задачи, затем проверьте HMAC-подпись на входящем POST и сразу читайте предподписанные URL стемов из тела запроса. Обработчики для FastAPI и Flask — на этой же странице.
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.
Что использовать — синхронный или асинхронный клиент?
По умолчанию берите синхронный (StemSplitter) — именно он используется в hello world из 12 строк и естественно вписывается в представление Django или задачу Celery. Переходите на AsyncStemSplitter, если вы уже работаете в FastAPI, Starlette или asyncio в ноутбуке: имена методов совпадают (await client.submit, await client.wait, await client.download), поэтому переключение стоит одного импорта и одного await на вызов.
Работает ли это с FastAPI и Flask?
Да — оба фреймворка поддерживаются полноценно. В разделе «Вебхуки» выше есть готовые обработчики для каждого: FastAPI использует async def webhook(request: Request) с verify_signature; Flask — синхронный маршрут @app.post. Оба проверяют HMAC-SHA256 с одним импортом (from aistemsplitter import verify_signature) и достают предподписанные URL стемов из JSON-тела без дополнительного парсинга.
Как установить пакет в virtualenv или Poetry-проект?
Стандартными инструментами: `python -m venv .venv && source .venv/bin/activate && pip install aistemsplitter` для venv; `poetry add aistemsplitter` для Poetry; `uv add aistemsplitter` для uv. Пакет распространяется как чисто Python-колёса (без нативной компиляции), поэтому установка проходит за секунды на любой платформе — без шимов pyenv, без предварительной установки FFmpeg и без драйверов GPU.
Будет ли качество в облаке соответствовать моему локальному htdemucs_ft?
Да. Мы предоставляем тот же файл модели, которому доверяет open-source-сообщество, — htdemucs_ft, а также htdemucs и htdemucs_6s, — поэтому результат побитно сопоставим с локальным запуском Demucs на той же модели и том же входе с поправкой на наши управляемые настройки инференса (размер батча, точность). Передавайте model='htdemucs_6s' при отправке, когда нужны стемы гитары и фортепиано.
Что делать, если возможностей типизированного SDK перестанет хватать и понадобится сырой HTTP?
Сразу переходите к /developers/api. SDK — это тонкая типизированная обёртка над теми же REST-эндпоинтами, к которым обращается curl-quickstart, поэтому заголовок авторизации (Authorization: Bearer ast_live_…), схема подписи вебхуков (HMAC-SHA256 в aistemsplitter-signature) и форматы ответов полностью совпадают. Подходы можно сочетать: отправлять задачу через SDK и получать статус через сырой httpx с собственной политикой повторов.
Как обрабатывать очень длинные аудио без тайм-аутов?
Есть две стратегии. (1) Используйте вебхуки — укажите webhook_url при отправке и полностью откажитесь от цикла опроса; API сам пришлёт результат, когда задача завершится, независимо от длительности. (2) Для файлов больше 50 МБ вызовите client.presign_upload(), чтобы получить URL для прямой загрузки в хранилище, загрузите файл через httpx multipart, а затем отправьте задачу с полученным audio_url вместо стриминга через наш шлюз.
Дальнейшие шаги
Запустите разделение на стемы до конца спринта.
Карта для создания ключа не нужна. Бесплатный тариф покрывает первые 10 минут; дальше — пакеты кредитов, которые не сгорают, по 0,08–0,14 $ за минуту в зависимости от объёма.