MAGI-2-preview

---

<p align="center"> <a href="https://sand.ai"><img alt="Sand.ai Homepage" src="https://img.shields.io/badge/Sand.ai-Homepage-333333.svg?logo=data:image/svg%2bxml;base64,PHN2ZyB3aWR0aD0iODAwIiBoZWlnaHQ9IjgwMCIgdmlld0JveD0iMCAwIDgwMCA4MDAiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxwYXRoIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBkPSJNMjI3IDIyNS4wODVDMjI3IDIwMi4zMDMgMjI3IDE5MC45MTIgMjMxLjQzNyAxODIuMjExQzIzNS4zMzkgMTc0LjU1NyAyNDEuNTY2IDE2OC4zMzQgMjQ5LjIyNiAxNjQuNDM0QzI1Ny45MzMgMTYwIDI2OS4zMzIgMTYwIDI5Mi4xMjkgMTYwSDUwNy44NzFDNTA5LjI5NSAxNjAgNTEwLjY3NiAxNjAgNTEyLjAxNCAxNjAuMDAxQzUzMi4wODIgMTYwLjAxNyA1NDIuNjExIDE2MC4yNzcgNTUwLjc3NCAxNjQuNDM0QzU1OC40MzQgMTY4LjMzNCA1NjQuNjYxIDE3NC41NTcgNTY4LjU2MyAxODIuMjExQzU3MyAxOTAuOTEyIDU3MyAyMDIuMzAzIDU3MyAyMjUuMDg1VjI1Ni41NThDNTczIDI5MS4zMTkgNTczIDMwOC43IDU2NS4wMzUgMzIzLjI3OUM1NTguNzU2IDMzNC43NzIgNTQzLjU2NSAzNDYuMTEgNTIzLjA3OCAzNTkuNjA1QzUxNC42NzQgMzY1LjE0MSA1MTAuNDcyIDM2Ny45MDkgNTA1LjYzOSAzNjcuOTM2QzUwMC44MDYgMzY3Ljk2NCA0OTYuNTAzIDM2NS4yIDQ4Ny44OTYgMzU5LjY3MUw0ODcuODk2IDM1OS42N0w0NjYuNDY5IDM0NS45MDVDNDU2Ljg3NSAzMzkuNzQyIDQ1Mi4wNzggMzM2LjY2IDQ1Mi4wNzggMzMyLjIxOEM0NTIuMDc4IDMyNy43NzcgNDU2Ljg3NSAzMjQuNjk1IDQ2Ni40NjkgMzE4LjUzMUw1MjYuNzgyIDI3OS43ODVDNTM1LjI5MSAyNzQuMzE5IDU0MC40MzUgMjY0LjkwMyA1NDAuNDM1IDI1NC43OTRDNTQwLjQzNSAyMzguMzg2IDUyNy4xMjUgMjI1LjA4NSA1MTAuNzA1IDIyNS4wODVIMjg5LjI5NUMyNzIuODc1IDIyNS4wODUgMjU5LjU2NSAyMzguMzg2IDI1OS41NjUgMjU0Ljc5NEMyNTkuNTY1IDI2NC45MDMgMjY0LjcwOSAyNzQuMzE5IDI3My4yMTggMjc5Ljc4NUw1MTMuMTggNDMzLjk0MUM1NDIuNDQxIDQ1Mi43MzggNTU3LjA3MSA0NjIuMTM3IDU2NS4wMzUgNDc2LjcxNkM1NzMgNDkxLjI5NCA1NzMgNTA4LjY3NSA1NzMgNTQzLjQzNlY1NzQuOTE1QzU3MyA1OTcuNjk3IDU3MyA2MDkuMDg4IDU2OC41NjMgNjE3Ljc4OUM1NjQuNjYxIDYyNS40NDQgNTU4LjQzNCA2MzEuNjY2IDU1MC43NzQgNjM1LjU2NkM1NDIuMDY3IDY0MCA1MzAuNjY4IDY0MCA1MDcuODcxIDY0MEgyOTIuMTI5QzI2OS4zMzIgNjQwIDI1Ny45MzMgNjQwIDI0OS4yMjYgNjM1LjU2NkMyNDEuNTY2IDYzMS42NjYgMjM1LjMzOSA2MjUuNDQ0IDIzMS40MzcgNjE3Ljc4OUMyMjcgNjA5LjA4OCAyMjcgNTk3LjY5NyAyMjcgNTc0LjkxNVY1NDMuNDM2QzIyNyA1MDguNjc1IDIyNyA0OTEuMjk0IDIzNC45NjUgNDc2LjcxNkMyNDEuMjQ0IDQ2NS4yMjIgMjU2LjQzMyA0NTMuODg2IDI3Ni45MTggNDQwLjM5MkMyODUuMzIyIDQzNC44NTYgMjg5LjUyNSA0MzIuMDg4IDI5NC4zNTcgNDMyLjA2QzI5OS4xOSA0MzIuMDMyIDMwMy40OTQgNDM0Ljc5NyAzMTIuMSA0NDAuMzI2TDMzMy41MjcgNDU0LjA5MUMzNDMuMTIyIDQ2MC4yNTQgMzQ3LjkxOSA0NjMuMzM2IDM0Ny45MTkgNDY3Ljc3OEMzNDcuOTE5IDQ3Mi4yMiAzNDMuMTIyIDQ3NS4zMDEgMzMzLjUyOCA0ODEuNDY1TDMzMy41MjcgNDgxLjQ2NUwyNzMuMjIgNTIwLjIwOEMyNjQuNzA5IDUyNS42NzUgMjU5LjU2NSA1MzUuMDkxIDI1OS41NjUgNTQ1LjIwMkMyNTkuNTY1IDU2MS42MTIgMjcyLjg3NyA1NzQuOTE1IDI4OS4yOTkgNTc0LjkxNUg1MTAuNzAxQzUyNy4xMjMgNTc0LjkxNSA1NDAuNDM1IDU2MS42MTIgNTQwLjQzNSA1NDUuMjAyQzU0MC40MzUgNTM1LjA5MSA1MzUuMjkxIDUyNS42NzUgNTI2Ljc4IDUyMC4yMDhMMjg2LjgyIDM2Ni4wNTNDMjU3LjU2IDM0Ny4yNTYgMjQyLjkyOSAzMzcuODU3IDIzNC45NjUgMzIzLjI3OUMyMjcgMzA4LjcgMjI3IDI5MS4zMTkgMjI3IDI1Ni41NThWMjI1LjA4NVoiIGZpbGw9IiNGRkZGRkYiLz4KPC9zdmc+Cg=="></a> <a href="https://sand.ai/blog/magi-2-preview"><img alt="Tech Blog" src="https://img.shields.io/badge/Tech%20Blog-MAGI--2%20Preview-333333"></a> <a href="https://huggingface.co/sand-ai/MAGI-2-preview"><img alt="Hugging Face" src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-MAGI--2%20Preview-ffc107"></a> <a href="https://x.com/SandAI_HQ"><img alt="Twitter Follow" src="https://img.shields.io/badge/Twitter-Sand.ai-white?logo=x&logoColor=white"/></a> <a href="LICENSE"><img alt="Apache 2.0 License" src="https://img.shields.io/badge/License-Apache%202.0-green?logo=apache"></a> </p>

MAGI-2 Preview

Magi-2 Preview is a 114B-parameter unified audio-video generation model that activates just 6B parameters per token. Built on MagiMoE and co-designed across architecture, systems, and data, it explores an efficient path to scaling video generation. The architecture, the training system built around it, and the data pipeline are described in MAGI-2 Preview: Scaling Video Generation Models Efficiently; the weights are on Hugging Face at sand-ai/MAGI-2-preview.

This repository is the inference code. It generates video from a text prompt (T2V) or from a prompt plus a still image (I2V), with sound generated alongside the video and muxed into the output file. Clips are 10 seconds long, which is the only duration the model currently supports. Generation runs in two stages: magi2_preview denoises the clip at low resolution, and magi2_refiner takes that result up to 1080p.

Requirements

• NVIDIA Hopper GPUs, 8 of them.
• Python 3.12 and a recent CUDA toolkit.
• ffmpeg on PATH, to mux the audio track. Without it the video is still written, just silently.

Setup

Docker

The published image, sandai/magi-2-preview, already has the dependencies built, including the ones that need a compiler:

docker pull sandai/magi-2-preview:latest
docker run --gpus all -it -v /path/to/ckpt:/workspace/ckpt sandai/magi-2-preview:latest

There is a tag per commit as well, sandai/magi-2-preview:<commit>. Name that one when reporting a result, because latest moves; the image also records what it was built from in /etc/magi2-build-info.

Building it yourself is only necessary to change a dependency version, or to work somewhere the registry is not reachable:

docker build -t magi-2-preview:local .

From source

pip install -r requirements.txt

MAGI-2 also needs MagiAttention and MagiCompiler. The pinned revisions are recorded as build args in the Dockerfile.

Checkpoints

Weights are not bundled with the code. Everything the pipeline loads lives in one Hugging Face repository, sand-ai/MAGI-2-preview, roughly 307 GB in total. Download it into ckpt/ in the repository root, which is gitignored:

pip install huggingface_hub
hf download sand-ai/MAGI-2-preview --local-dir ckpt

The directory names in that repository are the ones the configs already expect, so nothing needs renaming afterwards:

ckpt/
├── preview/                            # preview stage: 56 safetensors shards + index
├── refiner/                            # refiner stage: 3 shards + index
├── text_encoder/                       # text encoder
├── vae/                                # video VAE
│   └── Wan2.2_VAE.pth
├── stable-audio-open-1.0/              # audio VAE
└── turbo_vae/                          # fast VAE decoder
    ├── TurboV3-Wan22-TinyShallow_7_7.json
    └── checkpoint.ckpt

The configs under configs/ reference these as ${MAGI2_CKPT_ROOT}/<name>, and that variable defaults to <repo>/ckpt. To keep weights somewhere else, point it at them rather than editing the configs:

export MAGI2_CKPT_ROOT=/data/magi2-weights

Prompts

The captions the model was trained on are long and structured, so a prompt written by hand underuses it. Two system prompts for a prompt-enhancement LLM are included: prompts/t2v.md for text to video, and prompts/i2v.md for a prompt plus a still image.

Use one as the system prompt of an instruction-following model, pass the raw prompt as the message (the still as well, for I2V), and feed the JSON caption it returns to the pipeline in place of the prompt. Both lay out the 10 seconds the model generates.

assets/ has both ends of that step. sample_000.txt through sample_002.txt are raw prompts, the kind you would hand to the enhancer; sample_enhanced_t2v.json is the shape one comes back in. The demo batch runs both, so enhancing is not a precondition for generating.

Running inference

scripts/run_demo.sh launches inference/pipeline/entry.py under torchrun on every visible GPU. It generates at 1080p, with seed 42 and the batch in assets/demo_samples.json:

bash scripts/run_demo.sh
SAMPLES=my_samples.json bash scripts/run_demo.sh   # a different batch
OUTPUT_DIR=output/run7 bash scripts/run_demo.sh

The script takes SAMPLES, OUTPUT_DIR, SEED and MASTER_PORT from the environment. Videos land in $OUTPUT_DIR/sample_000.mp4 and up, numbered by position in the batch.

A samples file is a JSON array with one entry per video. An entry carries its prompt inline as prompt or as a path in prompt_file, and a first frame in image; leaving image out makes it a T2V entry. The shipped batch runs the three stills in assets/ as I2V, the same three prompts again as T2V, and assets/sample_enhanced_t2v.json.

For a single clip, call the entry point directly:

torchrun --nproc_per_node=8 inference/pipeline/entry.py \
    --prompt "a red fox in snow" --output output/

It also takes --prompt-file, --image, --seed, --config, --output-width / --output-height, --num-inference-steps, --refiner-num-inference-steps and --deterministic. Of these only --seed, --samples and --output are reachable through run_demo.sh.

1080p runs configs/magi2_refiner.json: the preview stage generates 512x896 and the refiner takes that to 1088x1920. magi2_refiner.json extends magi2_preview.json and carries only what the refiner stage adds, so a shared setting is edited in one place.

1080p is a delivery tier, not the shape that gets generated. The VAE stride constrains every generated dimension to a multiple of 16, so the tier generates 1088 wide rather than 1080, and the video is written at that generated shape. Pass --output-width and --output-height to have the finished video rescaled to an exact size, 1080x1920 the way the reference delivers the tier.

Four environment variables decide where each large component sits between phases: MAGI2_TEXT_ENC_OFFLOAD_MODE, MAGI2_PREVIEW_OFFLOAD_MODE, MAGI2_REFINER_OFFLOAD_MODE and MAGI2_VAE_OFFLOAD_MODE, each one of cpu, gpu or roundtrip. The preview and the refiner default to roundtrip, staged in and out around the stage that needs them, because at 1080p neither fits on an 80GB card next to the other's activations.

Decoding uses the distilled turbo decoder from ckpt/turbo_vae, a temporal sliding window that runs on one rank per video. MAGI2_DETERMINISTIC=1, or --deterministic, makes the MoE scatter and the attention kernels bit-exact at some cost in speed. MAGI2_SAVE_LATENT_PATH writes the post-refiner latent of each sample to that directory.

License

Apache 2.0. See LICENSE.