Developer docs / AI Fabric tutorials
Music generation with ACE-Step
- GPU
- Volume
- Image DSL
Take it for a spin
The whole program in one file, ready to run.
import bladekit
import io
app = bladekit.app("music-gen")
# Checkpoints (~7 GB) are cached on a Volume so only the first run downloads them.
hf_cache = bladekit.Volume.from_name("hf-cache", create_if_missing=True)
# ACE-Step requires Python < 3.13; 3.12 is the platform default, so nothing special
# from a Python 3.12 venv too (AI Fabric run-mode matches client and image Python).
# The PyPI "ace_step" package is an incomplete sdist: install from GitHub.
image = (
bladekit.Image.debian_slim(python_version="3.12")
.apt_install("git", "ffmpeg")
# Pin the torch trio first: ACE-Step leaves them unpinned and PyPI's
# latest torch/torchvision/torchaudio can skew out of sync.
.pip_install("torch==2.8.0", "torchvision==0.23.0", "torchaudio==2.8.0")
.pip_install(
"git+https://github.com/ace-step/ACE-Step.git",
"hf_transfer",
)
.env({"HF_HOME": "/hf-cache", "HF_HUB_ENABLE_HF_TRANSFER": "1"})
)
_pipe = None
@app.function(gpu="RTX-A4500", image=image, timeout=1800, volumes={"/hf-cache": hf_cache})
def generate_music(prompt: str, duration_seconds: int = 15) -> bytes:
global _pipe
import soundfile as sf
from acestep.pipeline_ace_step import ACEStepPipeline
if _pipe is None:
# Downloads ACE-Step/ACE-Step-v1-3.5B into the Volume on first use,
# then loads it on the GPU (~2 min; cached runs skip the download).
_pipe = ACEStepPipeline(
checkpoint_dir="/hf-cache/ace-step-v1-3.5b", dtype="bfloat16"
)
# The pipeline writes audio to disk and returns [path, ..., params].
# save_path must end in ".wav" because the format is inferred from the extension.
outputs = _pipe(
prompt=prompt,
lyrics="[instrumental]",
audio_duration=float(duration_seconds),
infer_step=27,
guidance_scale=15.0,
save_path="/tmp/ace-output.wav",
format="wav",
)
audio_path = outputs[0]
# Re-encode to WAV in memory so callers always get RIFF/WAV bytes.
data, sample_rate = sf.read(audio_path)
buf = io.BytesIO()
sf.write(buf, data, samplerate=sample_rate, format="WAV")
return buf.getvalue()
@app.local_entrypoint()
def main():
import pathlib
wav = generate_music.remote(
"upbeat jazz piano trio, swing rhythm, warm recording"
)
pathlib.Path("music.wav").write_bytes(wav)
print(f"Saved music.wav ({len(wav) / 1e3:.0f} KB)")Run it
- ACE-Step needs Python < 3.13, and AI Fabric run-mode requires the client Python to MATCH the image, so create a 3.12 client venv first:
uv venv -p 3.12 .venv312 && uv pip install --python .venv312/bin/python bladekit, then use.venv312/bin/blade. - Save as
music_gen.py. Run.venv312/bin/blade run music_gen.py. - The PyPI
ace_steppackage is an incomplete sdist (missing half its modules), so the image installs from GitHub instead, with the torch trio pinned so PyPI can't skew torchaudio out of sync. - First run downloads the ~7 GB ACE-Step checkpoints into the
hf-cacheVolume; later runs skip it. A 15-second clip generates in well under a minute on the A4500. - Your track lands in
music.wavlocally. Tweakprompt,duration_seconds, or pass reallyricsinstead of[instrumental].
Concepts used: Cold start, GPU, Image build