Guide · Open source
How to use generative-models: run SV3D and SV4D from the command line
Updated · written with AI from the project's own documentation and checked against our catalogue data
Stability-AI/generative-models is the code release for Stability AI's video models SV3D, SV4D and SV4D 2.0, which create novel-view video of an object from a single image or from a video. This guide shows how to set up the environment, download the model weights and run the command-line scripts. By the end you will be able to generate a novel-view video from your own input file, provided you have a suitable GPU.
Generative ModelsStability-AI/generative-models · ★ 27.3k · MIT Install options & downloads Quick start
- 1Create the environment. Create a Python 3.10 virtual environment named .generativemodels and activate it.
- 2Install PyTorch with CUDA. Install PyTorch with the CUDA build that matches your GPU, as the README advises.
- 3Install the requirements. Run pip3 install -r requirements/pt2.txt and then pip3 install . from the repository root.
- 4Download the weights. Use huggingface-cli to download sv4d2.safetensors into the checkpoints folder.
- 5Run the sampler. Call scripts/sampling/simple_video_sample_4d2.py with your input_path and an output folder.
- 6Adjust for your GPU. If you run out of memory, set encoding_t and decoding_t to 1 or lower img_size to 512.
What the generative-models repository does
The repository holds the code for Stability AI's generative models, mainly video models that generate new views of an object. SV3D takes a single image and produces an orbiting video of it. SV4D and SV4D 2.0 take a video and generate novel-view video from it.
The models are released for research purposes, and the README shows command-line scripts for running them. It does not describe a polished consumer app.
- SV3D: image-to-video, 21 frames at 576x576, from one context image.
- SV4D: video-to-4D, generates 40 frames (5 video frames x 8 camera views) per pass.
- SV4D 2.0: trained to generate 48 frames (12 video frames x 4 camera views).
What you need before you install
The README lists four prerequisites: Python 3.10, PyTorch with CUDA (the exact version depends on your GPU), Hugging Face model weights such as sv4d2.safetensors, and a GPU with enough VRAM. The README does not state a specific VRAM amount, but its low-VRAM workarounds imply that significant memory is needed.
- Python 3.10
- PyTorch with CUDA, matched to your GPU and CUDA version
- Model weights from Hugging Face, for example sv4d2.safetensors
- A capable GPU; use the low-VRAM options below if memory is tight
Install generative-models with a virtual environment
Create and activate a Python 3.10 virtual environment, then install the dependencies from the requirements file and install the package. The README also notes that you should check the CUDA version before installing PyTorch.
- Install PyTorch first, selecting the CUDA index that matches your system; the README comment says to check your CUDA version.
- Run the requirements install, then install the package itself from the cloned repository.
python3.10 -m venv .generativemodels
source .generativemodels/bin/activate
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 # check CUDA version
pip3 install -r requirements/pt2.txt
pip3 install .
pip3 install -e git+https://github.com/Stability-AI/datapipelines.git@main#egg=sdataDownload the model weights
The model weights are hosted on Hugging Face. Place them in a folder named checkpoints/ inside the repository. The README gives a huggingface-cli command for the SV4D 2.0 weights.
- SV4D 2.0 main model: sv4d2.safetensors
- SV4D 2.0 8-view model: sv4d2_8views.safetensors
- SV4D: sv4d.safetensors; SV3D: sv3d_u.safetensors and sv3d_p.safetensors
huggingface-cli download stabilityai/sv4d2.0 sv4d2.safetensors --local-dir checkpointsRun SV4D 2.0 on a video or image sequence
Run the sampling script with an input path. The input can be a single gif or mp4 file, a folder of .jpg, .jpeg or .png frames, or a file name pattern matching frames. The README's quickstart uses a sample gif and writes results to an outputs folder.
Optional settings include num_steps, which defaults to 50 and can be lowered to shorten sampling time, and elevations_deg, which defaults to 0.0 (the same as the input view). For plain backgrounds you can add --remove_bg=True to use rembg.
- input_path: a gif or mp4 file, a folder of frames, or a filename pattern.
- num_steps: default 50; lower it for faster sampling.
- elevations_deg: specified elevation relative to the input view; default 0.0.
- remove_bg: set --remove_bg=True to remove the background with rembg on plain-background inputs.
python scripts/sampling/simple_video_sample_4d2.py --input_path assets/sv4d_videos/camel.gif --output_folder outputsReduce memory use on a smaller GPU
If you run out of VRAM, the README suggests two approaches: lower the number of frames encoded and decoded at a time, or lower the video resolution. For noisy real-world backgrounds, the README suggests segmenting the object first with Clipdrop or SAM2 before running SV4D.
- Set --encoding_t=1 and --decoding_t=1 to process one frame at a time.
- Lower resolution with --img_size=512.
- For real-world footage with noisy backgrounds, segment the foreground object with Clipdrop or SAM2 first.
Generate an orbit from a single image with SV3D
To make an orbiting video from one image, download sv3d_u.safetensors into checkpoints/ and run the standalone sampling script with the sv3d_u version flag. The input should ideally be a white-background image with one object, according to the README.
- SV3D_u generates orbital videos from a single image without camera conditioning.
- SV3D_p also accepts orbital camera paths and supports a specified elevation, for example 30.0 in the README.
python scripts/sampling/simple_video_sample.py --input_path <path/to/image.png> --version sv3d_uWhat people use it for
- Turning a single product photo with a white background into an orbiting video for research review.
- Generating novel-view videos of a moving object from a short gif or mp4 clip.
- Experimenting with video-to-4D generation as part of academic work on novel-view synthesis.
- Comparing outputs from SV3D and SV4D on the same input to study consistency across views.
Frequently asked questions
Is generative-models free to use?
The repository is released under the MIT licence. The model weights are described in the README as released for research purposes, and the README does not give commercial terms, so check the model licence before any commercial use.
What GPU do I need to run generative-models?
The README does not list a minimum GPU or VRAM figure. It says PyTorch with CUDA depends on your GPU, and it offers low-VRAM options such as --encoding_t=1, --decoding_t=1 and --img_size=512, which suggests significant memory is needed.
How do I install generative-models?
Create a Python 3.10 virtual environment, activate it, install PyTorch with CUDA, then run pip3 install -r requirements/pt2.txt followed by pip3 install . from the repository. Download the Hugging Face weights into checkpoints/ before running the scripts.
Why does my run fail with an out-of-memory error?
The README's suggested fix is to set --encoding_t=1 and --decoding_t=1, which encode and decode one frame at a time, or to lower the input resolution with --img_size=512. Check that your PyTorch CUDA build matches your GPU as well.
What is the difference between SV3D and SV4D?
According to the README, SV3D takes a single image and generates an orbiting video. SV4D takes a video and generates novel-view video from it, and SV4D 2.0 is the newer version with higher fidelity and better consistency.
What are alternatives to generative-models?
The comparable projects listed for this item are Zero123, Stable Video Diffusion, Wonder3D and Nerfstudio. Pick one of these if you need a different model family or a more polished workflow.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use generative-models if you are a researcher or developer comfortable with Python, CUDA and command-line tools, and you have a capable GPU and a use that fits the research-only release. If you want a ready-made app or clear commercial terms, look at the comparable projects instead.
Install options & downloads