中文阅读

HunyuanWorld-Voyager

---

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.

🔥🔥🔥 News!!

• 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.

Export Point Cloud

After generating RGB-D video content, you can export ply file as follows:

cd data_engine

python3 convert_point.py --folder_path "your_input_condition_folder" --video_path "your_output_video_path"

⚙️ 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}
}

📧 Contact

Please send emails to [email protected] if there is any question

Acknowledgements

We would like to thank HunyuanWorld, Hunyuan3D, and HunyuanVideo. We also thank VGGT, MoGE, Metric3D, for their open research and exploration.