SANA-WM

SANA-WM adalah model dunia dari gambar ke video yang dikendalikan kamera, dibangun di atas SANA. Diberikan gambar bingkai pertama, prompt teks, dan lintasan kamera (baik pose c2w eksplisit maupun string aksi WASD/IJKL), model ini menghasilkan video yang gerakannya mengikuti jalur kamera yang diminta.

Inferensi berjalan dalam dua tahap:

1. Tahap 1 — SANA-WM DiT. DiT bidireksional dengan 1,6 miliar parameter yang menggunakan atensi linear GDN-Triton dan cabang kontrol kamera UCPE. Sampling menggunakan penjadwal Euler flow-matching bergaya LTX dengan timestep per token; frame laten pertama berfungsi sebagai jangkar kondisioning.
2. Tahap 2 — Refiner LTX-2 (opsional). Pipeline refiner Euler sink-bidirectional yang terpisah (SanaWMLTX2Refiner) yang membungkus SanaWMLTX2RefinerTransformer3DModel + LTX2TextConnectors dan text encoder Gemma-3, dijalankan selama 3 langkah sigma terdistilasi.

Kedua tahap melakukan dekoding melalui VAE AutoencoderKLLTX2Video.

Model yang tersedia:

SANA-WM dilatih pada resolusi tetap 704×1280. dtype yang direkomendasikan adalah untuk bobot transformer — pertahankan text encoder dalam torch.bfloat16 dan VAE dalam torch.float32 untuk numerik terbaik. Pipeline mengharapkan intrinsik kamera [fx, fy, cx, cy] dalam koordinat piksel gambar-asli; transformasi resize-and-center-crop diterapkan secara internal.

Inferensi

import torch
from PIL import Image

from diffusers import SanaWMPipeline
from diffusers.utils import export_to_video

pipe = SanaWMPipeline.from_pretrained(
    "Efficient-Large-Model/SANA-WM_bidirectional-diffusers",
    torch_dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()  # ~45 GB of weights — offload between stages

# SANA-WM was trained on the LTX-2 VAE in framewise mode with tiling enabled. Without these
# settings the VAE encodes the whole (B, C, T, H, W) clip in one shot, which gives subtly
# different numerics from the released checkpoint.
pipe.vae.enable_tiling()
pipe.vae.use_framewise_encoding = True
pipe.vae.use_framewise_decoding = True
pipe.vae.tile_sample_stride_num_frames = 64
pipe.vae.tile_sample_min_num_frames = 96

prompt = "A car driving across a vast desert plain at golden hour."
output = pipe(
    image=Image.open("input.png").convert("RGB"),
    prompt=prompt,
    action="w-80,jw-40,w-40",        # WASD-style action DSL: forward 80f, jump+forward 40f, forward 40f
    intrinsics=[800.0, 800.0, 845.0, 464.0],  # fx, fy, cx, cy in original-image pixels
    num_frames=161,
    num_inference_steps=60,
    guidance_scale=5.0,
    generator=torch.Generator(device="cuda").manual_seed(42),
    output_type="latent",            # hand the latents to the refiner below
)

Lewati action=None dan sediakan pose c2w Anda sendiri ((F, 4, 4) array numpy) untuk menggerakkan lintasan kamera secara eksplisit. Buang output_type="latent" untuk mendapatkan video langsung dari tahap 1 dan lewati refiner.

Tahap 2 — penyempurna LTX-2

SanaWMLTX2Refiner dirilis sebagai repositori tersendiri, seperti cara SDXL memisahkan base dan refiner. Sampaikan VAE dari pipeline base agar bobotnya dibagikan alih-alih dimuat dua kali:

from diffusers import SanaWMLTX2Refiner

refiner = SanaWMLTX2Refiner.from_pretrained(
    "Efficient-Large-Model/SANA-WM_bidirectional-diffusers-refiner",
    vae=pipe.vae,
    torch_dtype=torch.bfloat16,
)
refiner.enable_model_cpu_offload()

frames = refiner(output.latent, prompt, fps=16)
export_to_video(list(frames), "sana_wm.mp4", fps=16)

Tanpa vae, refiner mengembalikan latents yang telah disempurnakan alih-alih video, yang berguna jika Anda ingin melakukan decoding sendiri.

Aktifkan offloading pada keduanya pipeline, atau bebaskan stage 1 sebelum stage 2 (pipe.transformer.to("cpu")). Kedua stage tersebut bersama-sama berukuran sekitar 45 GB dalam torch.bfloat16, dan mempertahankan keduanya tetap berada di satu kartu 80 GB menyisakan ruang yang terlalu sedikit untuk activations. Perhatikan juga bahwa stage 2 menghormati torch_dtype: memuat refiner dalam torch.float32 akan menggandakan memori secara kasar dan mengubah output sedikit.

Jika Anda tidak memiliki intrinsik kamera, blok modular yang di-hosting dapat memperkirakan intrinsik tersebut dari satu frame. Blok ini berada di luar diffusers karena menarik Pi3X — sebuah dependensi tambahan dan checkpoint kedua — sehingga tidak ada yang diunduh sampai Anda memintanya:

from diffusers import ModularPipeline

# One-time per image. Requires `pip install pi3-vision`.
estimator = ModularPipeline.from_pretrained(
    "Efficient-Large-Model/pi3x-intrinsics-estimator", trust_remote_code=True
)
estimator.load_components(dtype=torch.bfloat16)
intrinsics = estimator(image=Image.open("input.png").convert("RGB"), output="intrinsics")

Mengonversi checkpoint yang dirilis

Jika Anda memiliki rilis sumber SANA-WM (bukan snapshot diffusers yang sudah dikonversi sebelumnya), jalankan skrip konversi sekali:

python scripts/convert_sana_wm_to_diffusers.py \
    --src Efficient-Large-Model/SANA-WM_bidirectional \
    --dst ./SANA-WM_bidirectional-diffusers

Ini menulis dua direktori: pipeline dasar di --dst, dan refiner tahap-2 di sampingnya di ./SANA-WM_bidirectional-diffusers-refiner (ganti dengan --dst-refiner). Kemudian muat masing-masing dari path lokalnya seperti biasa.

Komponen

• tokenizer — GemmaTokenizerFast
• text_encoder — Gemma-2 (mengembalikan hidden states decoder)
• vae — AutoencoderKLLTX2Video (LTX-2, spasial ×32 / temporal ×8)
• transformer — SanaWMTransformer3DModel, DiT bidireksional dengan 1,6 miliar parameter
• scheduler — FlowMatchEulerDiscreteScheduler

Refiner tahap-2 adalah repositori terpisah dengan transformer (SanaWMLTX2RefinerTransformer3DModel), connectors (LTX2TextConnectors), tokenizer, text_encoder Gemma-3, dan scheduler miliknya sendiri. Refiner ini tidak memiliki vae sendiri — gunakan vae dari pipeline dasar.

SanaWMPipeline

>>> import torch
>>> from PIL import Image
>>> from diffusers import SanaWMPipeline

>>> pipe = SanaWMPipeline.from_pretrained(
...     "Efficient-Large-Model/SANA-WM_bidirectional-diffusers", torch_dtype=torch.bfloat16
... ).to("cuda")

>>> output = pipe(
...     image=Image.open("input.png").convert("RGB"),
...     prompt="A car driving across a vast desert plain at golden hour.",
...     action="w-80,jw-40,w-40",
...     intrinsics=[800.0, 800.0, 845.0, 464.0],  # fx, fy, cx, cy in original-image pixels
...     num_inference_steps=60,
... )
>>> # output.frames is (T, H, W, 3) float np.ndarray in [0, 1] (diffusers convention).

SanaWMLTX2Refiner

Refiner tahap-2 LTX-2 adalah DiffusionPipeline mandiri yang menerima latents tahap-1. Berikan vae (milik pipeline dasar, sehingga bobotnya dibagikan) agar latents tersebut didekode menjadi video; tanpa vae, pipeline ini mengembalikan latents yang telah disempurnakan.

SanaWMPipelineOutput