kiapi 0.1.0__py3-none-any.whl

kiapi/capabilities/_exceptions/ValidationError.py

@@ -0,0 +1,2 @@
+class ValidationError(ValueError):
+    """Request violates a cap or a capability constraint."""

kiapi/capabilities/_helpers/attach_mflux_progress.py

@@ -0,0 +1,50 @@
+"""Idempotently register a denoising-progress callback on an mflux model.
+
+Called right before ``model.generate_image(...)`` in each image family's
+generation helper. Every mflux model exposes ``model.callbacks`` (a
+``CallbackRegistry``) and runs ``ctx.in_loop(t, latents)`` once per denoise step;
+the registry routes anything with ``call_in_loop`` to the in-loop list.
+
+The callback holds no per-job state — it reads the job's ambient
+:class:`ProgressReporter` (see core/job) each step — so a single instance can stay
+registered on a resident model and serve every job (silently no-op when no job is
+bound). Models built via different paths (resident ``load`` vs one-off transient
+builds) all funnel through here, and resident models persist across jobs, so
+registration is idempotent to avoid stacking a fresh callback per call.
+"""
+
+from typing import Any
+
+from kiapi.core.job import ProgressReporter
+
+
+class _MfluxProgressCallback:
+    def __init__(self, label: str = "denoising") -> None:
+        self._label = label
+
+    def call_in_loop(
+        self,
+        t: int,
+        seed: int,
+        prompt: str,
+        latents: Any,
+        config: Any,
+        time_steps: Any,
+    ) -> None:
+        # ``time_steps`` is the tqdm driving the loop; ``.n`` counts steps
+        # completed before this one, so ``n + 1`` are done after it.
+        total = getattr(time_steps, "total", 0) or getattr(
+            config, "num_inference_steps", 0
+        )
+        done = getattr(time_steps, "n", 0) + 1
+        ProgressReporter.current().step(int(done), int(total), self._label)
+
+
+def attach_mflux_progress(model: Any, *, label: str = "denoising") -> None:
+    registry = getattr(model, "callbacks", None)
+    if registry is None:
+        return  # not an mflux model with a callback registry; nothing to do
+    in_loop = getattr(registry, "in_loop", [])
+    if any(isinstance(cb, _MfluxProgressCallback) for cb in in_loop):
+        return  # already attached (resident model reused across jobs)
+    registry.register(_MfluxProgressCallback(label=label))

kiapi/capabilities/_helpers/get_file_path.py

@@ -0,0 +1,20 @@
+from kiapi.core.file import FileRef, FileStore, resolve_file_ref
+
+from .._exceptions.CapabilityError import CapabilityError
+
+
+def get_file_path(
+    file_store: FileStore,
+    file: str | FileRef,
+    *,
+    kind: str,
+) -> str:
+    try:
+        if isinstance(file, str):
+            rec = file_store.get(file)
+            if rec is None:
+                raise FileNotFoundError(f"unknown {kind} file_id {file!r}")
+            return rec.path
+        return resolve_file_ref(file_store, file, kind=kind).path
+    except (FileNotFoundError, ValueError) as exc:
+        raise CapabilityError(str(exc)) from exc

kiapi/capabilities/_helpers/resolve_file_ref.py

@@ -0,0 +1,16 @@
+from kiapi.core.file import FileRef, FileStore, ResolvedFileRef
+from kiapi.core.file import resolve_file_ref as core_resolve_file_ref
+
+from .._exceptions.CapabilityError import CapabilityError
+
+
+def resolve_file_ref(
+    file_store: FileStore,
+    ref: FileRef,
+    *,
+    kind: str,
+) -> ResolvedFileRef:
+    try:
+        return core_resolve_file_ref(file_store, ref, kind=kind)
+    except (FileNotFoundError, ValueError) as exc:
+        raise CapabilityError(str(exc)) from exc

kiapi/capabilities/acestep/README.ja.md

@@ -0,0 +1,174 @@
+# acestep
+
+[English](README.md) | **日本語**
+
+[ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5) で、下記の機能を提供します。
+- 音楽生成
+- 既存の曲のスタイル変換
+- 曲の一部の再生成
+- 音源分離
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/audio/acestep/generate` | 音楽生成 | プロンプト, 詩, 時間, 言語を指定して曲を生成。 |
+| `POST /v1/audio/acestep/cover` | スタイル変換 | 既存の曲の構成を保ったまま別スタイルに変換。 |
+| `POST /v1/audio/acestep/repaint` | 一部再生成 | 曲の時間範囲を再生成。 |
+| `POST /v1/audio/acestep/extract` | 音源分離 | 曲のボーカル・ドラムなどの音源を分離。 |
+| `GET /v1/audio/acestep/models` | モデル一覧 | 利用可能なモデルの一覧を返す。 |
+| `GET /v1/audio/acestep/openapi.json` | OpenAPI | 詳細な入出力仕様、使い方、TIPS を返す。 |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/audio/acestep/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/audio/acestep/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/audio/acestep/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [ace-step](https://github.com/ace-step/ACE-Step-1.5) | MIT | ACE-Step 1.5 本体。 |
+| [transformers](https://github.com/huggingface/transformers) | Apache-2.0 | ace-step が要求する 4.x 系。 |
+| [PyTorch](https://github.com/pytorch/pytorch) | BSD-3-Clause | ace-step の依存として導入される。 |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [ACE-Step/acestep-v15-xl-base](https://huggingface.co/ACE-Step/acestep-v15-xl-base) | MIT | 不要 | 19 GB | `xl-base`（デフォルト）。32ステップ / `guidance_scale=7.0`、最高品質。30秒の音声で約25秒（M4 Max）。 |
+| [ACE-Step/Ace-Step1.5](https://huggingface.co/ACE-Step/Ace-Step1.5) | MIT | 不要 | 9.4 GB | `turbo`（8ステップ、`guidance_scale` を無視）の DiT に加え、5Hz LM・VAE・Qwen3-Embedding-0.6B を同梱。速度重視で15秒で約4秒（M4 Max）。 |
+| [Qwen/Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B) | Apache-2.0 | 不要 | 1.1 GB | テキストエンコーダ。ACE-Step/Ace-Step1.5 に同梱。 |
+
+## Notes
+
+- **transformers 4.x の隔離**:
+  ACE-Step 1.5 は **transformers 4.x** をピンしており、スタック全体が必要とする **transformers 5.x** と競合する。
+  そのため ace-step は専用の **venv** でサブプロセスとして実行する。
+  メインプロセスは **`acestep` を import しない**。
+- **ローカル配置**:
+  `KIAPI_ACESTEP_PYTHON_PATH`, `KIAPI_ACESTEP_PROJECT_ROOT`, `KIAPI_ACESTEP_CHECKPOINT_DIR`
+  が未指定の場合、ACE-Step 用の venv / project / checkpoints は
+  `core/app` の user data dir 配下の `acestep/` に配置する。
+- **IPC**:
+  メインプロセスはワーカーと stdin/stdout 上の小さな行指向 JSON プロトコルで通信する。
+  各行に `@@KIAPI@@` センチネルを前置。それ以外の stdout はノイズ扱い。
+  加えて音声 I/O はファイルパスでやり取りする。
+  progress コールバックはジョブの `ProgressReporter` に転送される。
+
+## Quickstart
+
+### generate - 音楽生成
+
+```bash
+jq -n \
+--arg prompt "Modern J-Pop, 132 BPM, bright piano, emotional electric guitar, upbeat drums" \
+--arg lyrics '[Verse 1]
+加速する世界の中で
+君の声が聴こえてくる
+
+[Chorus]
+僕らは光を追いかける
+終わらない夢の向こうへ
+' \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  lyrics: $lyrics,
+  duration: 30,
+  lang: "ja",
+  seed: 1
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/audio/acestep/generate \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o song.wav
+```
+
+### cover - スタイル変換
+
+```bash
+SRC=$(
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/files -F "file=@song.wav" |
+jq -r .file_id
+)
+
+jq -n \
+--arg src "$SRC" \
+--arg prompt "City Pop, groovy bass, smooth guitar, laid-back 80s production" \
+'{
+  model: "turbo",
+  mode: "sync",
+  source: {type: "file_id", file_id: $src},
+  prompt: $prompt,
+  strength: 0.7,
+  seed: 1
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/audio/acestep/cover \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o cover.wav
+```
+
+`strength`: 0.3 = 緩い再解釈。0.7 = 構成を保ちつつスタイルを変える。1.0 = 厳密。
+
+### repaint - 時間範囲を再生成
+
+```bash
+SRC=$(
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/files -F "file=@song.wav" |
+jq -r .file_id
+)
+
+jq -n \
+--arg src "$SRC" \
+--arg prompt "Dramatic orchestral strings, emotional swell, cinematic" \
+'{
+  model: "turbo",
+  mode: "sync",
+  source: {type: "file_id", file_id: $src},
+  prompt: $prompt,
+  start: 15,
+  end: 30,
+  strength: 0.6,
+  seed: 1
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/audio/acestep/repaint \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o repainted.wav
+```
+
+`start`/`end` は秒単位（`end: -1` = 最後まで）。
+
+### extract - 音源分離
+
+```bash
+SRC=$(
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/files -F "file=@song.wav" |
+jq -r .file_id
+)
+
+RESP=$(
+jq -n \
+--arg src "$SRC" \
+'{
+  model: "turbo",
+  mode: "sync",
+  source: {type: "file_id", file_id: $src},
+  targets: ["vocals", "drums", "bass", "other"]
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/audio/acestep/extract \
+-H 'Content-Type: application/json' \
+-H 'Accept: application/json' \
+--data-binary @-
+)
+
+# 各音源をダウンロード（stems[] にターゲット名が入る）
+echo "$RESP" | jq -c '.result.stems[]' | while read -r s; do
+  TARGET=$(echo "$s" | jq -r .target); FID=$(echo "$s" | jq -r .file_id)
+  curl -o "${TARGET}.wav" http://localhost:${PORT:-8000}/v1/files/$FID/download
+done
+```

kiapi/capabilities/acestep/README.md

@@ -0,0 +1,167 @@
+# acestep
+
+**English** | [日本語](README.ja.md)
+
+[ACE-Step 1.5](https://github.com/ace-step/ACE-Step-1.5) provides the following functions.
+- Music generation
+- Style conversion of existing songs
+- Regenerate part of a song
+- Sound source separation
+
+## API
+
+| Endpoint | Name | Description |
+|---|---|---|
+| `POST /v1/audio/acestep/generate` | Music generation | Generate a song by specifying prompt, poem, time, and language. |
+| `POST /v1/audio/acestep/cover` | Style conversion | Convert an existing song to a different style while preserving its structure. |
+| `POST /v1/audio/acestep/repaint` | Partial regeneration | Regenerate the time range of the song. |
+| `POST /v1/audio/acestep/extract` | Sound source separation | Separate the sound sources such as vocals and drums of a song. |
+| `GET /v1/audio/acestep/models` | Model list | Returns a list of available models. |
+| `GET /v1/audio/acestep/openapi.json` | OpenAPI | Returns detailed input/output specifications, usage, and TIPS. |
+
+## API Docs
+
+- [OpenAPI JSON](https://kiarina.github.io/kiapi/v1/audio/acestep/openapi.json)
+- [Swagger UI](https://kiarina.github.io/kiapi/v1/audio/acestep/docs.html)
+- [ReDoc](https://kiarina.github.io/kiapi/v1/audio/acestep/redoc.html)
+
+## Dependencies
+
+| Package | License | Description |
+|---|---|---|
+| [ace-step](https://github.com/ace-step/ACE-Step-1.5) | MIT | ACE-Step 1.5 main body. |
+| [transformers](https://github.com/huggingface/transformers) | Apache-2.0 | 4.x version required by ace-step. |
+| [PyTorch](https://github.com/pytorch/pytorch) | BSD-3-Clause | Introduced as a dependency of ace-step. |
+
+## Models
+
+| Model | License | Terms | Size | Description |
+|---|---|---|---:|---|
+| [ACE-Step/acestep-v15-xl-base](https://huggingface.co/ACE-Step/acestep-v15-xl-base) | MIT | Not required | 19 GB | `xl-base` (default). 32 steps / `guidance_scale=7.0`, highest quality. Approximately 25 seconds with 30 seconds of audio (M4 Max). |
+| [ACE-Step/Ace-Step1.5](https://huggingface.co/ACE-Step/Ace-Step1.5) | MIT | Not required | 9.4 GB | In addition to `turbo` (8 steps, ignoring `guidance_scale`) DiT, 5Hz LM, VAE, and Qwen3-Embedding-0.6B are included. Focusing on speed, 15 seconds is about 4 seconds (M4 Max). |
+| [Qwen/Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B) | Apache-2.0 | Not required | 1.1 GB | Text encoder. Included with ACE-Step/Ace-Step1.5. |
+
+## Notes
+
+- **Isolation of transformers 4.x**:
+  ACE-Step 1.5 pins **transformers 4.x** and conflicts with **transformers 5.x**, which requires the entire stack.
+  Therefore, ace-step is executed as a subprocess in a dedicated **venv**.
+  The main process does not import `acestep`.
+- **Local placement**:
+  `KIAPI_ACESTEP_PYTHON_PATH`, `KIAPI_ACESTEP_PROJECT_ROOT`, `KIAPI_ACESTEP_CHECKPOINT_DIR`
+  If is not specified, venv / project / checkpoints for ACE-Step is
+  Place it in `acestep/` under the user data dir of `core/app`.
+- **IPC**:
+  The main process communicates with workers using a small line-oriented JSON protocol on stdin/stdout.
+  Prefix each line with `@@KIAPI@@` sentinel. Other stdout is treated as noise.
+  In addition, audio I/O is exchanged using file paths.
+  The progress callback is forwarded to the job's `ProgressReporter`.
+
+## Quickstart
+
+### generate - music generation
+```bash
+jq -n \
+--arg prompt "Modern J-Pop, 132 BPM, bright piano, emotional electric guitar, upbeat drums" \
+--arg lyrics '[Verse 1]
+加速する世界の中で
+君の声が聴こえてくる
+
+[Chorus]
+僕らは光を追いかける
+終わらない夢の向こうへ
+' \
+'{
+  model: "turbo",
+  mode: "sync",
+  prompt: $prompt,
+  lyrics: $lyrics,
+  duration: 30,
+  lang: "ja",
+  seed: 1
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/audio/acestep/generate \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o song.wav
+```
+### cover - style conversion
+```bash
+SRC=$(
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/files -F "file=@song.wav" |
+jq -r .file_id
+)
+
+jq -n \
+--arg src "$SRC" \
+--arg prompt "City Pop, groovy bass, smooth guitar, laid-back 80s production" \
+'{
+  model: "turbo",
+  mode: "sync",
+  source: {type: "file_id", file_id: $src},
+  prompt: $prompt,
+  strength: 0.7,
+  seed: 1
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/audio/acestep/cover \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o cover.wav
+```
+`strength`: 0.3 = loose reinterpretation. 0.7 = Change style while keeping composition. 1.0 = strict.
+
+### repaint - regenerate time range
+```bash
+SRC=$(
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/files -F "file=@song.wav" |
+jq -r .file_id
+)
+
+jq -n \
+--arg src "$SRC" \
+--arg prompt "Dramatic orchestral strings, emotional swell, cinematic" \
+'{
+  model: "turbo",
+  mode: "sync",
+  source: {type: "file_id", file_id: $src},
+  prompt: $prompt,
+  start: 15,
+  end: 30,
+  strength: 0.6,
+  seed: 1
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/audio/acestep/repaint \
+-H 'Content-Type: application/json' \
+--data-binary @- \
+-o repainted.wav
+```
+`start`/`end` is in seconds (`end: -1` = until the end).
+
+### extract - sound source separation
+```bash
+SRC=$(
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/files -F "file=@song.wav" |
+jq -r .file_id
+)
+
+RESP=$(
+jq -n \
+--arg src "$SRC" \
+'{
+  model: "turbo",
+  mode: "sync",
+  source: {type: "file_id", file_id: $src},
+  targets: ["vocals", "drums", "bass", "other"]
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/audio/acestep/extract \
+-H 'Content-Type: application/json' \
+-H 'Accept: application/json' \
+--data-binary @-
+)
+
+# 各音源をダウンロード（stems[] にターゲット名が入る）
+echo "$RESP" | jq -c '.result.stems[]' | while read -r s; do
+  TARGET=$(echo "$s" | jq -r .target); FID=$(echo "$s" | jq -r .file_id)
+  curl -o "${TARGET}.wav" http://localhost:${PORT:-8000}/v1/files/$FID/download
+done
+```

kiapi/capabilities/acestep/__init__.py

@@ -0,0 +1,37 @@
+"""acestep family - ACE-Step 1.5 music generation, run in an isolated venv subprocess.
+
+Endpoints: ``POST /v1/audio/acestep/{generate,cover,repaint,extract}``. ace-step
+pins transformers 4.x, which conflicts with chat/embedding's transformers 5.x, so
+it cannot share kiapi's process. Instead each variant (preset) is a resident spec
+whose payload is a long-lived worker subprocess (launched from the ACE-Step venv);
+kiapi talks to it over a small JSON pipe protocol and treats it as a normal
+resident model - budgeted, evictable (``release`` = terminate), TTL-swept.
+
+The subprocess's memory is NOT visible in kiapi's own RSS, so ``weight_gb`` here
+is an estimate (the registry value is authoritative for budgeting); load() logs
+the child's real RSS so these can be tuned on device.
+"""
+
+from ._helpers.register import register
+from ._operations.handle_cover import handle_cover
+from ._operations.handle_extract import handle_extract
+from ._operations.handle_generate import handle_generate
+from ._operations.handle_repaint import handle_repaint
+from ._settings import settings_manager
+from ._views.cover_request import CoverRequest
+from ._views.extract_request import ExtractRequest
+from ._views.generate_request import GenerateRequest
+from ._views.repaint_request import RepaintRequest
+
+__all__ = [
+    "CoverRequest",
+    "ExtractRequest",
+    "GenerateRequest",
+    "RepaintRequest",
+    "handle_cover",
+    "handle_extract",
+    "handle_generate",
+    "handle_repaint",
+    "register",
+    "settings_manager",
+]

kiapi/capabilities/acestep/_constants/description.py

@@ -0,0 +1,122 @@
+DESCRIPTION = """Music generation (ACE-Step 1.5): compose, cover, repaint, extract.
+
+Four operations on ACE-Step 1.5: `/generate` (text2music — a new song from a
+style prompt + lyrics), `/cover` (re-style an existing track), `/repaint`
+(regenerate a time range), and `/extract` (separate into stems). ACE-Step runs in
+an isolated subprocess (it pins an older transformers than chat/embedding); the
+first request after idle pays a load cost of tens of seconds, then it stays
+resident until the idle TTL or budget pressure frees it.
+
+## Upstream docs
+- [ACE-Step](https://github.com/ace-step/ACE-Step) — the upstream model
+
+## Models
+- **xl-base** (default) — highest quality. 32 inference steps, CFG 7.0.
+  ~25 s per 30 s of audio on M4 Max.
+- **turbo** — fastest. 8 inference steps, no CFG. ~4 s per 15 s on M4 Max. Great
+  for prototyping / iterating on prompts.
+
+Pick the preset with `model`; discover variants at `GET /v1/audio/acestep/models`.
+The sampling overrides (`inference_steps`, `guidance_scale`, `shift`) default to
+the preset's tuned values — set them only to deviate.
+
+## Source workflow
+`/cover`, `/repaint`, and `/extract` operate on an existing track: POST the source
+WAV to `/v1/files` to get a `file_id`, then pass it as `source`. `/generate` needs
+no source.
+
+## Prompt tips
+Describe the SOUND, not the story — a narrative sentence beats a keyword list.
+Useful elements to mention:
+- **genre**: Modern J-Pop / Acoustic Jazz / Dark Trap / Lo-fi Hip-hop / Anime OST
+- **tempo**: 132 BPM / slow and intimate / driving beat / half-time feel
+- **instruments**: bright piano / smooth saxophone / 808 sub-bass / nylon guitar
+- **vocal**: emotional female vocal / whispered delivery / powerful male tenor
+- **mood**: melancholic / triumphant / cozy / aggressive / dreamy / nostalgic
+- **production**: polished radio-ready / lo-fi vinyl texture / orchestral / live band
+
+- **good**: "A melancholic piano ballad where soft female vocals weave through
+  gentle strings, intimate and heartbreaking. 80 BPM."
+- **bad**: "piano, sad, female, slow"
+
+## Lyrics format (generate)
+Use `[Square Bracket]` section tags at the start of a line: `[Intro]`,
+`[Verse 1]`, `[Pre-Chorus]`, `[Chorus]`, `[Bridge]`, `[Instrumental]`, `[Outro]`.
+Modifiers work too, e.g. `[Verse 1 - Female]`, `[Chorus - Both]`,
+`[Bridge - Whispered]`. Set lyrics to `[Instrumental]` for no vocals. Keep the
+lyric length proportionate to `duration` — sparse lyrics over a long duration
+degrade quality.
+
+## Language codes (lang, generate)
+ISO 639-1: `ja` Japanese, `en` English, `ko` Korean, `zh` Mandarin, `yue`
+Cantonese, `es` Spanish, `fr` French, `de` German, …. `unknown` auto-detects
+(may reduce quality).
+
+## TIPS
+- For a quick track, call `sync` without `Accept: application/json` to get the raw
+  WAV bytes straight back (`curl -o out.wav`). `/extract` is multi-artifact, so it
+  always returns Job JSON.
+- Reuse a `seed` (≠ -1) with the same params to reproduce a result.
+- Run `kiapi activate` ahead of time so the first request doesn't pay a cold-start
+  weight download.
+
+## Examples
+
+### Generate (sync, turbo)
+```sh
+jq -n \\
+--arg prompt "Modern J-Pop, 132 BPM, bright piano, emotional electric guitar, upbeat drums, polished anime opening production" \\
+--arg lyrics '[Verse 1]
+加速する世界の中で
+君の声が聴こえてくる
+
+[Pre-Chorus]
+夜明け前の空に
+まだ見ぬ明日を描いた
+
+[Chorus]
+僕らは光を追いかける
+終わらない夢の向こうへ
+何度でも手を伸ばして
+新しい風になる
+' \\
+'{
+  "model": "turbo",
+  "mode": "sync",
+  "prompt": $prompt,
+  "lyrics": $lyrics,
+  "duration": 30,
+  "lang": "ja",
+  "seed": 1
+}' |
+curl -sS -X POST http://localhost:${PORT:-8000}/v1/audio/acestep/generate \\
+  -H 'Content-Type: application/json' \\
+  --data-binary @- \\
+  -o acestep_generate.wav
+```
+
+### Cover (async, turbo)
+```sh
+curl -sS http://HOST:PORT/v1/audio/acestep/cover \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "model": "turbo",
+    "mode": "async",
+    "source": "<file_id>",
+    "prompt": "lo-fi chillhop, warm tape",
+    "strength": 0.7
+  }'
+# -> {"job_id": "..."}; poll GET /v1/jobs/{job_id}
+```
+
+### Extract stems
+```sh
+curl -sS http://HOST:PORT/v1/audio/acestep/extract \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "source": "<file_id>",
+    "targets": ["vocals", "drums", "bass", "other"]
+  }'
+# -> one job, artifacts = 4 file_ids (one WAV per target)
+```
+"""

kiapi/capabilities/acestep/_exceptions/ace_step_engine_error.py

@@ -0,0 +1,2 @@
+class AceStepEngineError(RuntimeError):
+    pass