中文阅读
We introduce HunyuanWorld-Voyager, a novel video diffusion framework that generates world-consistent 3D point-cloud sequences from a single image with user-defined camera path. Voyager can generate 3D-consistent scene videos for world exploration following custom camera trajectories. It can also generate aligned depth and RGB video for efficient and direct 3D reconstruction.
Sep 2, 2025: 👋 We release the code and model weights of HunyuanWorld-Voyager. Download.
Join our Wechat and Discord group to discuss and find help from us.
Wechat Group Xiaohongshu X Discord
🎥 Demo
Demo Video
demo.mp4
Camera-Controllable Video Generation
Input Generated Video output.mp4 output7.mp4 output9.mp4
Multiple Applications
Video Reconstruction
Generated Video Reconstructed Point Cloud output1.mp4 output2.mp4
Image-to-3D Generation
output5.mp4 output11.mp4
Video Depth Estimation
depth.mp4 depth2.mp4
☯️ HunyuanWorld-Voyager Introduction
Architecture
Voyager consists of two key components:
(1) World-Consistent Video Diffusion: A unified architecture that jointly generates aligned RGB and depth video sequences, conditioned on existing world observation to ensure global coherence.
(2) Long-Range World Exploration: An efficient world cache with point culling and an auto-regressive inference with smooth video sampling for iterative scene extension with context-aware consistency.
To train Voyager, we propose a scalable data engine, i.e., a video reconstruction pipeline that automates camera pose estimation and metric depth prediction for arbitrary videos, enabling large-scale, diverse training data curation without manual 3D annotations. Using this pipeline, we compile a dataset of over 100,000 video clips, combining real-world captures and synthetic Unreal Engine renders.
Performance
Quantitative comparison on WorldScore Benchmark. 🔴 indicates the 1st, 🟢 indicates the 2nd, 🟡 indicates the 3rd. Method WorldScore Average Camera Control Object Control Content Alignment 3D Consistency Photometric Consistency Style Consistency Subjective Quality WonderJourney 🟡63.75 🟡84.6 37.1 35.54 80.6 79.03 62.82 🟢66.56 WonderWorld 🟢72.69 🔴92.98 51.76 🔴71.25 🔴86.87 85.56 70.57 49.81 EasyAnimate 52.85 26.72 54.5 50.76 67.29 47.35 🟡73.05 50.31 Allegro 55.31 24.84 🟡57.47 🟡51.48 70.5 69.89 65.6 47.41 Gen-3 60.71 29.47 🟢62.92 50.49 68.31 🟢87.09 62.82 🟡63.85 CogVideoX-I2V 62.15 38.27 40.07 36.73 🟢86.21 🔴88.12 🟢83.22 62.44 Voyager 🔴77.62 🟢85.95 🔴66.92 🟢68.92 🟡81.56 🟡85.99 🔴84.89 🔴71.09
📜 Requirements
The following table shows the requirements for running Voyager (batch size = 1) to generate videos:
Model Resolution GPU Peak Memory HunyuanWorld-Voyager 540p 60GB
An NVIDIA GPU with CUDA support is required. The model is tested on a single 80G GPU. Minimum : The minimum GPU memory required is 60GB for 540p. Recommended : We recommend using a GPU with 80GB of memory for better generation quality.
Tested operating system: Linux
🛠️ Dependencies and Installation
Begin by cloning the repository:
git clone https://github.com/Tencent-Hunyuan/HunyuanWorld-Voyager cd HunyuanWorld-Voyager
Installation Guide for Linux
We recommend CUDA versions 12.4 or 11.8 for the manual installation.
# 1. Create conda environment conda create -n voyager python==3.11.9 # 2. Activate the environment conda activate voyager # 3. Install PyTorch and other dependencies using conda # For CUDA 12.4 conda install pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.4 -c pytorch -c nvidia # 4. Install pip dependencies python -m pip install -r requirements.txt python -m pip install transformers==4.39.3 # 5. Install flash attention v2 for acceleration (requires CUDA 11.8 or above) python -m pip install flash-attn # 6. Install xDiT for parallel inference (It is recommended to use torch 2.4.0 and flash-attn 2.6.3) python -m pip install xfuser==0.4.2
In case of running into float point exception(core dump) on the specific GPU type, you may try the following solutions:
# Making sure you have installed CUDA 12.4, CUBLAS>=12.4.5.8, and CUDNN>=9.00 (or simply using our CUDA 12 docker image). pip install nvidia-cublas-cu12==12.4.5.8 export LD_LIBRARY_PATH=/opt/conda/lib/python3.8/site-packages/nvidia/cublas/lib/
To create your own input conditions, you also need to install the following dependencies:
pip install --no-deps git+https://github.com/microsoft/MoGe.git pip install scipy==1.11.4 pip install git+https://github.com/EasternJournalist/utils3d.git@c5daf6f6c244d251f252102d09e9b7bcef791a38
🧱 Download Pretrained Models
A detailed guidance for downloading pretrained models is shown here. Briefly,
huggingface-cli download tencent/HunyuanWorld-Voyager --local-dir ./ckpts
🔑 Inference
Create Input Condition
We provide several input examples in the examples folder. You can find the corresponding input text in the prompt.txt file. If you'd like to use your own input image, you can run the following command:
cd data_engine python3 create_input.py --image_path " your_input_image " --render_output_dir " examples/case/ " --type " forward "
We provide the following types of camera path:
forward
backward
left
right
turn_left
turn_right You can also modify the camera path in the create_input.py file.
Single-GPU Inference
cd HunyuanWorld-Voyager python3 sample_image2video.py \ --model HYVideo-T/2 \ --input-path " examples/case1 " \ --prompt " An old-fashioned European village with thatched roofs on the houses. " \ --i2v-stability \ --infer-steps 50 \ --flow-reverse \ --flow-shift 7.0 \ --seed 0 \ --embedded-cfg-scale 6.0 \ --use-cpu-offload \ --save-path ./results
You can add "--use-context-block" to add the context block in the inference.
Parallel Inference on Multiple GPUs by xDiT
xDiT is a Scalable Inference Engine for Diffusion Transformers (DiTs) on multi-GPU Clusters. It has successfully provided low-latency parallel inference solutions for a variety of DiTs models, including mochi-1, CogVideoX, Flux.1, SD3, etc. This repo adopted the Unified Sequence Parallelism (USP) APIs for parallel inference of the HunyuanVideo-I2V model.
For example, to generate a video with 8 GPUs, you can use the following command:
cd HunyuanWorld-Voyager ALLOW_RESIZE_FOR_SP=1 torchrun --nproc_per_node=8 \ sample_image2video.py \ --model HYVideo-T/2 \ --input-path " examples/case1 " \ --prompt " An old-fashioned European village with thatched roofs on the houses. " \ --i2v-stability \ --infer-steps 50 \ --flow-reverse \ --flow-shift 7.0 \ --seed 0 \ --embedded-cfg-scale 6.0 \ --save-path ./results \ --ulysses-degree 8 \ --ring-degree 1
The number of GPUs equals the product of --ulysses-degree and --ring-degree. Feel free to adjust these parallel configurations to optimize performance.
Latency (Sec) for 512x768 (49 frames 50 steps) on 8 x H20 GPU 1 2 4 8 1925 1018 (1.89x) 534 (3.60x) 288 (6.69x)
Gradio Demo
We also provide a Gradio demo for the HunyuanWorld-Voyager model.
You can run the following command to start the demo:
cd HunyuanWorld-Voyager python3 app.py
You need to first upload an image and choose a camera direction to create a condition video. Then, you can type your text prompt and generate the final RGB-D video.
⚙️ Data Engine
We also release the data engine of HunyuanWorld-Voyager, which can be used to generate scalable data for RGB-D video training. Please refer to data_engine for more details.
🔗 BibTeX
If you find Voyager useful for your research and applications, please cite using this BibTeX:
@article { huang2025voyager , title = { Voyager: Long-Range and World-Consistent Video Diffusion for Explorable 3D Scene Generation } , author = { Huang, Tianyu and Zheng, Wangguandong and Wang, Tengfei and Liu, Yuhao and Wang, Zhenwei and Wu, Junta and Jiang, Jie and Li, Hui and Lau, Rynson WH and Zuo, Wangmeng and Guo, Chunchao } , journal = { arXiv preprint arXiv:2506.04225 } , year = { 2025 } }
Acknowledgements
We would like to thank HunyuanWorld, Hunyuan3D-2, and HunyuanVideo-I2V. We also thank VGGT, MoGE, Metric3D, for their open research and exploration.