SANA-WM

SANA-WM est un modèle de monde image-vers-vidéo contrôlé par caméra, construit sur la base de SANA. À partir d'une image de première image, d'un prompt texte et d'une trajectoire de caméra (soit des poses c2w explicites, soit une chaîne d'actions WASD/IJKL), il génère une vidéo dont le mouvement suit le chemin de caméra demandé.

L'inférence s'exécute en deux étapes :

1. Étape 1 — SANA-WM DiT. Un DiT bidirectionnel de 1,6 milliard de paramètres avec une attention linéaire GDN-Triton et une branche de contrôle caméra UCPE. L'échantillonnage utilise un planificateur Euler de correspondance de flux de type LTX avec des pas de temps par jeton ; le premier cadre latent est l'ancrage de conditionnement.
2. Étape 2 — Rafineur LTX-2 (facultatif). Un pipeline de raffinement Euler bidirectionnel distinct (SanaWMLTX2Refiner) qui encapsule SanaWMLTX2RefinerTransformer3DModel + LTX2TextConnectors et un encodeur de texte Gemma-3, exécuté sur 3 étapes de sigma distillées.

Les deux étapes décodent via le VAE AutoencoderKLLTX2Video.

Modèles disponibles :

SANA-WM est entraîné à une résolution fixe de 704×1280. Le dtype recommandé pour les poids du transformer est torch.bfloat16 — conservez l'encodeur de texte en torch.bfloat16 et le VAE en torch.float32 pour une meilleure précision numérique. Le pipeline s'attend à des intrinsèques de caméra [fx, fy, cx, cy] dans les coordonnées de pixels de l'image d'origine ; la transformation de redimensionnement et de recadrage centré est appliquée en interne.

Inférence

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
)

Passez action=None et fournissez vos propres poses c2w (tableau numpy (F, 4, 4)) pour piloter explicitement la trajectoire de la caméra. Supprimez output_type="latent" pour obtenir la vidéo directement depuis l'étape 1 et ignorer le raffineur.

Étape 2 — le raffineur LTX-2

SanaWMLTX2Refiner est fourni sous forme de dépôt distinct, à la manière dont SDXL sépare le modèle de base et le raffineur. Transmettez le VAE du pipeline de base afin que les poids soient partagés plutôt que chargés deux fois :

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)

Sans vae, le refiner renvoie des latents affinés au lieu de la vidéo, ce qui est utile si vous souhaitez effectuer le décodage vous-même.

Activez le déchargement sur les deux pipelines, ou libérez l’étape 1 avant l’étape 2 (pipe.transformer.to("cpu")). Les deux étapes représentent environ 45 Go en torch.bfloat16, et les maintenir toutes deux sur une seule carte de 80 Go laisse trop peu de place pour les activations. Notez également que l’étape 2 respecte torch_dtype : charger le raffineur en torch.float32 double approximativement sa mémoire et modifie légèrement la sortie.

Si vous ne disposez pas des intrinsèques de la caméra, un bloc modulaire hébergé peut les estimer à partir d’une seule image. Il se trouve en dehors de diffusers car il intègre Pi3X — une dépendance supplémentaire et un second point de contrôle — de sorte que rien n’est téléchargé tant que vous ne le demandez pas :

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")

Conversion du point de contrôle publié

Si vous disposez de la version source SANA-WM (et non du instantané diffusers pré-converti), exécutez le script de conversion une seule fois :

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

Cela écrit deux répertoires : le pipeline de base dans --dst, et le raffineur de l’étape 2 à côté, dans ./SANA-WM_bidirectional-diffusers-refiner (à remplacer par --dst-refiner). Chargez ensuite chacun depuis son chemin local, comme d’habitude.

Composants

• tokenizer — GemmaTokenizerFast
• text_encoder — Gemma-2 (renvoie les états cachés du décodeur)
• vae — AutoencoderKLLTX2Video (LTX-2, spatial ×32 / temporal ×8)
• transformer — SanaWMTransformer3DModel, DiT bidirectionnel de 1,6 milliard de paramètres
• scheduler — FlowMatchEulerDiscreteScheduler

Le raffineur de l’étape 2 est un dépôt distinct disposant de son propre transformer (SanaWMLTX2RefinerTransformer3DModel), de ses connectors (LTX2TextConnectors), de son tokenizer, de son text_encoder Gemma-3 et de son scheduler. Il ne possède pas de vae propre — transmettez celui du pipeline de base.

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

Le raffineur de l’étape 2 de LTX-2 est un DiffusionPipeline autonome qui reçoit les latents de l’étape 1. Fournissez-lui un vae (celui du pipeline de base, afin que les poids soient partagés) pour qu’il décode en vidéo ; sans celui-ci, il renvoie des latents raffinés.

SanaWMPipelineOutput