ACE-Step/acestep-v15-xl-base-diffusers

1---2license: mit3library_name: diffusers4pipeline_tag: text-to-audio5tags:6  - diffusers7  - acestep8  - audio9  - music10  - text-to-music11  - flow-matching12base_model: ACE-Step/acestep-v15-xl-base13---14 15# ACE-Step v1.5 XL Base Diffusers16 17Diffusers-format checkpoint of [ACE-Step v1.5 XL Base](https://huggingface.co/ACE-Step/acestep-v15-xl-base) - the base 5B-parameter flow-matching DiT for text-to-music generation (`hidden_size=2560`, 32 layers, 32 heads; `encoder_hidden_size=2048` on the condition encoder).18 19This repository is the official Diffusers-format version of the ACE-Step v1.5 XL Base checkpoint. It can be loaded directly with `AceStepPipeline`, which is available in `huggingface/diffusers`.20 21Weights are produced by `scripts/convert_ace_step_to_diffusers.py` from the upstream release and packaged in the standard Diffusers pipeline layout (`model_index.json` + one subdirectory per module), so the full pipeline can be loaded in a single `from_pretrained` call.22 23## Usage24 25Install Diffusers from source until the next package release includes `AceStepPipeline`.26 27```bash28pip install git+https://github.com/huggingface/diffusers.git29```30 31```python32import torch33import soundfile as sf34from diffusers import AceStepPipeline35 36pipe = AceStepPipeline.from_pretrained(37    "ACE-Step/acestep-v15-xl-base-diffusers",38    torch_dtype=torch.bfloat16,39)40pipe = pipe.to("cuda")41 42# Long-form audio: enable VAE tiling to keep decode memory bounded.43pipe.vae.enable_tiling()44 45output = pipe(46    prompt="An upbeat synthwave track with driving drums and a catchy lead",47    lyrics="[Verse]\nNeon lights are calling me\n[Chorus]\nRide the wave tonight",48    audio_duration=30.0,49    num_inference_steps=50,50    guidance_scale=7.0,51    shift=3.0,52    generator=torch.Generator(device="cuda").manual_seed(42),53)54 55audio = output.audios[0]  # (channels, samples), 48 kHz56sf.write("acestep-xl-base.wav", audio.T.cpu().float().numpy(), pipe.sample_rate)57```58 59Unlike the turbo checkpoint, XL Base is not guidance-distilled. The pipeline uses ACE-Step's APG guidance path when `guidance_scale > 1.0`; `num_inference_steps=50`, `guidance_scale=7.0`, and `shift=3.0` are the recommended defaults. Pass `num_inference_steps=50` explicitly so generation does not use the lower-step turbo setting.60 61For batched prompts with padding and FlashAttention, use the variable-length backend:62 63```python64pipe.transformer.set_attention_backend("flash_varlen")65pipe.condition_encoder.set_attention_backend("flash_varlen")66```67 68For single-prompt generation, the regular `flash` backend is also suitable.69 70## Repository layout71 72```73├── model_index.json74├── transformer/        # AceStepTransformer1DModel (DiT, 5B params, bf16)75├── condition_encoder/  # AceStepConditionEncoder (with baked-in silence_latent)76├── audio_tokenizer/    # AceStepAudioTokenizer77├── audio_token_detokenizer/ # AceStepAudioTokenDetokenizer78├── vae/                # AutoencoderOobleck (48 kHz stereo)79├── text_encoder/       # Qwen3-Embedding-0.6B80├── tokenizer/          # Qwen3 tokenizer81├── scheduler/          # FlowMatchEulerDiscreteScheduler config82└── silence_latent.pt   # Raw reference (kept for debugging; not needed at runtime)83```84 85## License86 87- ACE-Step weights: MIT (same as [upstream](https://huggingface.co/ACE-Step/acestep-v15-xl-base))88- `text_encoder/` (Qwen3-Embedding-0.6B): Apache 2.0 - redistributed per Qwen's license89 90## Citation91 92```93@misc{gong2026acestep,94  title = {ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation},95  author = {Junmin Gong, Yulin Song, Wenxiao Zhao, Sen Wang, Shengyuan Xu, Jing Guo},96  howpublished = {\url{https://github.com/ace-step/ACE-Step-1.5}},97  year = {2026},98  note = {GitHub repository}99}100```101