Tencent-Hunyuan/Hunyuan3D-1

Tencent-Hunyuan/Hunyuan3D-1

Description: Tencent Hunyuan3D-1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation

Language: Python

License: NOASSERTION

Stars: 3476

Forks: 276

Open issues: 30

Created: 2024-10-31T09:04:57Z

Pushed: 2025-11-19T07:07:41Z

Default branch: main

Fork: no

Archived: no

README: [English](README.md) | [简体中文](README_zh_cn.md)

Tencent Hunyuan3D-1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation

🔥🔥🔥 News!!

• Jul 26, 2025: 🤗 We release the first open-source, simulation-capable, immersive 3D world generation model, HunyuanWorld-1.0!
• Jun 13, 2025: 🤗 We release the first production-ready 3D asset generation model Hunyuan3D 2.1!
• Jan 21, 2025: 🤗 Enjoy exciting 3D generation on our website Hunyuan3D Studio!
• Jan 21, 2025: 🤗 Release inference code and pretrained models of Hunyuan3D 2.0.
• Jan 21, 2025: 🤗 Release Hunyuan3D 2.0. Please give it a try via huggingface space our official site!

• Nov 21, 2024: 🤗 We have introduced the new Baking module. Please give it a try!
• Nov 20, 2024: 🤗 We have added a Chinese version of the README.
• Nov 18, 2024: 🤗 Third-party developers have uploaded their ComfyUI. We appreciate their contributions! [[1]](https://github.com/jtydhr88/ComfyUI-Hunyuan3D-1-wrapper)[[2]](https://github.com/MrForExample/ComfyUI-3D-Pack)[[3]](https://github.com/TTPlanetPig/Comfyui_Hunyuan3D)
• Nov 5, 2024: 🤗 We support demo running image_to_3d generation now. Please check the [script](#using-gradio) below.
• Nov 5, 2024: 🤗 We support demo running text_to_3d generation now. Please check the [script](#using-gradio) below.

📑 Open-source Plan

• [x] Inference
• [x] Checkpoints
• [x] Baking
• [ ] ComfyUI
• [ ] Training
• [ ] Distillation Version
• [ ] TensorRT Version

Abstract

While 3D generative models have greatly improved artists' workflows, the existing diffusion models for 3D generation suffer from slow generation and poor generalization. To address this issue, we propose a two-stage approach named Hunyuan3D-1.0 including a lite version and a standard version, that both support text- and image-conditioned generation.

In the first stage, we employ a multi-view diffusion model that efficiently generates multi-view RGB in approximately 4 seconds. These multi-view images capture rich details of the 3D asset from different viewpoints, relaxing the tasks from single-view to multi-view reconstruction. In the second stage, we introduce a feed-forward reconstruction model that rapidly and faithfully reconstructs the 3D asset given the generated multi-view images in approximately 7 seconds. The reconstruction network learns to handle noises and in-consistency introduced by the multi-view diffusion and leverages the available information from the condition image to efficiently recover the 3D structure.

Our framework involves the text-to-image model, i.e., Hunyuan-DiT, making it a unified framework to support both text- and image-conditioned 3D generation. Our standard version has 3x more parameters than our lite and other existing model. Our Hunyuan3D-1.0 achieves an impressive balance between speed and quality, significantly reducing generation time while maintaining the quality and diversity of the produced assets.

🎉 Hunyuan3D-1 Architecture

📈 Comparisons

We have evaluated Hunyuan3D-1.0 with other open-source 3d-generation methods, our Hunyuan3D-1.0 received the highest user preference across 5 metrics. Details in the picture on the lower left.

The lite model takes around 10 seconds to produce a 3D mesh from a single image, while the standard model takes roughly 25 seconds. The plot laid out in the lower right demonstrates that Hunyuan3D-1.0 achieves an optimal balance between quality and efficiency.

Get Started

Begin by cloning the repository:

git clone https://github.com/tencent/Hunyuan3D-1
cd Hunyuan3D-1

Installation Guide for Linux

We provide an env_install.sh script file for setting up environment.

conda create -n hunyuan3d-1 python=3.9 or 3.10 or 3.11 or 3.12
conda activate hunyuan3d-1

pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu121
bash env_install.sh

# or
pip3 install -r requirements.txt --index-url https://download.pytorch.org/whl/cu121
pip3 install git+https://github.com/facebookresearch/pytorch3d@stable
pip3 install git+https://github.com/NVlabs/nvdiffrast

because of dust3r, we offer a guide:

cd third_party
git clone --recursive https://github.com/naver/dust3r.git

cd ../third_party/weights
wget https://download.europe.naverlabs.com/ComputerVision/DUSt3R/DUSt3R_ViTLarge_BaseDecoder_512_dpt.pth

💡Other tips for envrionment installation

Optionally, you can install xformers or flash_attn to acclerate computation:

pip install xformers --index-url https://download.pytorch.org/whl/cu121

pip install flash_attn

Most environment errors are caused by a mismatch between machine and packages. You can try manually specifying the version, as shown in the following successful cases:

# python3.9
pip install torch==2.0.1 torchvision==0.15.2 --index-url https://download.pytorch.org/whl/cu118

when install pytorch3d, the gcc version is preferably greater than 9, and the gpu driver should not be too old.

Download Pretrained Models

The models are available at https://huggingface.co/tencent/Hunyuan3D-1:

+ Hunyuan3D-1/lite, lite model for multi-view generation. + Hunyuan3D-1/std, standard model for multi-view generation. + Hunyuan3D-1/svrm, sparse-view reconstruction model.

To download the model, first install the huggingface-cli. (Detailed instructions are available here.)

python3 -m pip install "huggingface_hub[cli]"

Then download the model using the following commands:

mkdir weights
huggingface-cli download tencent/Hunyuan3D-1 --local-dir ./weights

mkdir weights/hunyuanDiT
huggingface-cli download Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled --local-dir ./weights/hunyuanDiT

Inference

For text to 3d generation, we supports…