--- language: - en - zh library_name: hunyuan3d-2 license: other license_name: tencent-hunyuan-community license_link: https://huggingface.co/tencent/Hunyuan3D-2/blob/main/LICENSE.txt pipeline_tag: image-to-3d tags: - image-to-3d - text-to-3d ---

“ Living out everyone’s imagination on creating and manipulating 3D assets.”

This repository contains the models of the paper [Hunyuan3D 2.5: Towards High-Fidelity 3D Assets Generation with Ultimate Details](https://huggingface.co/papers/2506.16504). For code and more details on how to use it, refer to the [Github repository](https://github.com/Tencent/Hunyuan3D-2). ## 🔥 News - June 23, 2025: 📄 Release the system technical report of [Hunyuan3D 2.5](https://arxiv.org/abs/2506.16504). - June 13, 2025: 🤗 Release [Hunyuan3D-2.1](https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1), fully open-sourced with new PBR model, VAE encoder, and all training code. - Apr 1, 2025: 🤗 Release turbo paint model [Hunyuan3D-Paint-v2-0-Turbo](https://huggingface.co/tencent/Hunyuan3D-2/tree/main/hunyuan3d-paint-v2-0-turbo), and multiview texture generation pipeline, try it [here](examples/fast_texture_gen_multiview.py)! Stay tuned for our new texture generation model [RomanTex](https://github.com/oakshy/RomanTex) and PBR material generation [MaterialMVP](https://github.com/ZebinHe/MaterialMVP/)! - Mar 19, 2025: 🤗 Release turbo model [Hunyuan3D-2-Turbo](https://huggingface.co/tencent/Hunyuan3D-2/), [Hunyuan3D-2mini-Turbo](https://huggingface.co/tencent/Hunyuan3D-2mini/) and [FlashVDM](https://github.com/Tencent/FlashVDM). - Mar 18, 2025: 🤗 Release multiview shape model [Hunyuan3D-2mv](https://huggingface.co/tencent/Hunyuan3D-2mv) and 0.6B shape model [Hunyuan3D-2mini](https://huggingface.co/tencent/Hunyuan3D-2mini). - Feb 14, 2025: 🛠️ Release texture enhancement module, please obtain high-definition textures via [here](minimal_demo.py)! - Feb 3, 2025: 🐎 Release [Hunyuan3D-DiT-v2-0-Fast](https://huggingface.co/tencent/Hunyuan3D-2/tree/main/hunyuan3d-dit-v2-0-fast), our guidance distillation model that could half the dit inference time, see [here](minimal_demo.py) for usage. - Jan 27, 2025: 🛠️ Release Blender addon for Hunyuan3D 2.0, Check it out [here](#blender-addon). - Jan 23, 2025: 💬 We thank community members for creating [Windows installation tool](https://github.com/YanWenKun/Hunyuan3D-2-WinPortable), ComfyUI support with [ComfyUI-Hunyuan3DWrapper](https://github.com/kijai/ComfyUI-Hunyuan3DWrapper) and [ComfyUI-3D-Pack](https://github.com/MrForExample/ComfyUI-3D-Pack) and other awesome [extensions](#community-resources). - Jan 21, 2025: 💬 Enjoy exciting 3D generation on our website [Hunyuan3D Studio](https://3d.hunyuan.tencent.com)! - Jan 21, 2025: 🤗 Release inference code and pretrained models of [Hunyuan3D 2.0](https://huggingface.co/tencent/Hunyuan3D-2). Please give it a try via [huggingface space](https://huggingface.co/spaces/tencent/Hunyuan3D-2) and our [official site](https://3d.hunyuan.tencent.com)! > Join our **[Wechat](#)** and **[Discord](https://discord.gg/dNBrdrGGMa)** group to discuss and find help from us. | Wechat Group | Xiaohongshu | X | Discord | |--------------------------------------------------|-------------------------------------------------------|---------------------------------------------|---------------------------------------------------| |

| ## **Abstract** In this report, we present Hunyuan3D 2.5, a robust suite of 3D diffusion models aimed at generating high-fidelity and detailed textured 3D assets. Hunyuan3D 2.5 follows two-stages pipeline of its previous version Hunyuan3D 2.0, while demonstrating substantial advancements in both shape and texture generation. In terms of shape generation, we introduce a new shape foundation model -- LATTICE, which is trained with scaled high-quality datasets, model-size, and compute. Our largest model reaches 10B parameters and generates sharp and detailed 3D shape with precise image-3D following while keeping mesh surface clean and smooth, significantly closing the gap between generated and handcrafted 3D shapes. In terms of texture generation, it is upgraded with phyiscal-based rendering (PBR) via a novel multi-view architecture extended from Hunyuan3D 2.0 Paint model. Our extensive evaluation shows that Hunyuan3D 2.5 significantly outperforms previous methods in both shape and end-to-end texture generation.

## ☯️ **Hunyuan3D 2.5** ### Architecture Hunyuan3D 2.5 follows two-stages pipeline of its previous version Hunyuan3D 2.0, while demonstrating substantial advancements in both shape and texture generation

### Performance We have evaluated Hunyuan3D 2.5 with other open-source as well as close-source 3d-generation methods. The numerical results indicate that Hunyuan3D 2.5 surpasses all baselines in the quality of generated textured 3D assets and the condition following ability. | Model | CMMD(⬇) | FID_CLIP(⬇) | FID(⬇) | CLIP-score(⬆) | |-------------------------|-----------|-------------|-------------|---------------| | Top Open-source Model1 | 3.591 | 54.639 | 289.287 | 0.787 | | Top Close-source Model1 | 3.600 | 55.866 | 305.922 | 0.779 | | Top Close-source Model2 | 3.368 | 49.744 | 294.628 | 0.806 | | Top Close-source Model3 | 3.218 | 51.574 | 295.691 | 0.799 | | Hunyuan3D 2.5 | **3.193** | **49.165** | **282.429** | **0.809** | Generation results of Hunyuan3D 2.5:

## 🎁 Models Zoo It takes 6 GB VRAM for shape generation and 16 GB for shape and texture generation in total. Hunyuan3D-2-1 Series | Model | Description | Date | Size | Huggingface | |----------------------|----------------новой---------------|------------|------|-----------------------------------------------------------------------------------------| | Hunyuan3D-DiT-v2-1 | Mini Image to Shape Model | 2025-06-13 | 3.0B | [Download](https://huggingface.co/tencent/Hunyuan3D-2.1/tree/main/hunyuan3d-dit-v2-1) | | Hunyuan3D-Paint-v2-1 | Texture Generation Model | 2025-06-13 | 1.3B | [Download](https://huggingface.co/tencent/Hunyuan3D-2.1/tree/main/hunyuan3d-paintpbr-v2-1) | Hunyuan3D-2mini Series | Model | Description | Date | Size | Huggingface | |-----------------------------|-------------------------------|------------|------|--------------------------------------------------------------------------------------------------| | Hunyuan3D-DiT-v2-mini-Turbo | Step Distillation Version | 2025-03-19 | 0.6B | [Download](https://huggingface.co/tencent/Hunyuan3D-2mini/tree/main/hunyuan3d-dit-v2-mini-turbo) | | Hunyuan3D-DiT-v2-mini-Fast | Guidance Distillation Version | 2025-03-18 | 0.6B | [Download](https://huggingface.co/tencent/Hunyuan3D-2mini/tree/main/hunyuan3d-dit-v2-mini-fast) | | Hunyuan3D-DiT-v2-mini | Mini Image to Shape Model | 2025-03-18 | 0.6B | [Download](https://huggingface.co/tencent/Hunyuan3D-2mini/tree/main/hunyuan3d-dit-v2-mini) | Hunyuan3D-2mv Series | Model | Description | Date | Size | Huggingface | |---------------------------|--------------------------------|------------|------|----------------------------------------------------------------------------------------------| | Hunyuan3D-DiT-v2-mv-Turbo | Step Distillation Version | 2025-03-19 | 1.1B | [Download](https://huggingface.co/tencent/Hunyuan3D-2mv/tree/main/hunyuan3d-dit-v2-mv-turbo) | | Hunyuan3D-DiT-v2-mv-Fast | Guidance Distillation Version | 2025-03-18 | 1.1B | [Download](https://huggingface.co/tencent/Hunyuan3D-2mv/tree/main/hunyuan3d-dit-v2-mv-fast) | | Hunyuan3D-DiT-v2-mv | Multiview Image to Shape Model | 2025-03-18 | 1.1B | [Download](https://huggingface.co/tencent/Hunyuan3D-2mv/tree/main/hunyuan3d-dit-v2-mv) | Hunyuan3D-2 Series | Model | Description | Date | Size | Huggingface | |----------------------------|-----------------------------|------------|------|-------------------------------------------------------------------------------------------| | Hunyuan3D-DiT-v2-0-Turbo | Step Distillation Model | 2025-03-19 | 1.1B | [Download](https://huggingface.co/tencent/Hunyuan3D-2/tree/main/hunyuan3d-dit-v2-0-turbo) | | Hunyuan3D-DiT-v2-0-Fast | Guidance Distillation Model | 2025-02-03 | 1.1B | [Download](https://huggingface.co/tencent/Hunyuan3D-2/tree/main/hunyuan3d-dit-v2-0-fast) | | Hunyuan3D-DiT-v2-0 | Image to Shape Model | 2025-01-21 | 1.1B | [Download](https://huggingface.co/tencent/Hunyuan3D-2/tree/main/hunyuan3d-dit-v2-0) | | Hunyuan3D-Paint-v2-0 | Texture Generation Model | 2025-01-21 | 1.3B | [Download](https://huggingface.co/tencent/Hunyuan3D-2/tree/main/hunyuan3d-paint-v2-0) | | Hunyuan3D-Paint-v2-0-Turbo | Distillation Texure Model | 2025-04-01 | 1.3B | [Download](https://huggingface.co/tencent/Hunyuan3D-2/tree/main/hunyuan3d-paint-v2-0-turbo) | | Hunyuan3D-Delight-v2-0 | Image Delight Model | 2025-01-21 | 1.3B | [Download](https://huggingface.co/tencent/Hunyuan3D-2/tree/main/hunyuan3d-delight-v2-0) | ## 🤗 Get Started with Hunyuan3D 2.0 Hunyuan3D 2.0 supports Macos, Windows, Linux. You may follow the next steps to use Hunyuan3D 2.0 via: - [Code](#code-usage) - [Gradio App](#gradio-app) - [API Server](#api-server) - [Blender Addon](#blender-addon) - [Official Site](#official-site) ### Install Requirements Please install Pytorch via the [official](https://pytorch.org/) site. Then install the other requirements via ```bash pip install -r requirements.txt pip install -e . # for texture cd hy3dgen/texgen/custom_rasterizer python3 setup.py install cd ../../.. cd hy3dgen/texgen/differentiable_renderer python3 setup.py install ``` ### Code Usage We designed a diffusers-like API to use our shape generation model - Hunyuan3D-DiT and texture synthesis model - Hunyuan3D-Paint. You could assess **Hunyuan3D-DiT** via: ```python from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2') mesh = pipeline(image='assets/demo.png')[0] ``` The output mesh is a [trimesh object](https://trimesh.org/trimesh.html), which you could save to glb/obj (or other format) file. For **Hunyuan3D-Paint**, do the following: ```python from hy3dgen.texgen import Hunyuan3DPaintPipeline from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline # let's generate a mesh first pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2') mesh = pipeline(image='assets/demo.png')[0] pipeline = Hunyuan3DPaintPipeline.from_pretrained('tencent/Hunyuan3D-2') mesh = pipeline(mesh, image='assets/demo.png') ``` Please visit [examples](examples) folder for more advanced usage, such as **multiview image to 3D generation** and * *texture generation for handcrafted mesh**. ### Gradio App You could also host a [Gradio](https://www.gradio.app/) App in your own computer via: Standard Version ```bash # Hunyuan3D-2mini python3 gradio_app.py --model_path tencent/Hunyuan3D-2mini --subfolder hunyuan3d-dit-v2-mini --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode # Hunyuan3D-2mv python3 gradio_app.py --model_path tencent/Hunyuan3D-2mv --subfolder hunyuan3d-dit-v2-mv --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode # Hunyuan3D-2 python3 gradio_app.py --model_path tencent/Hunyuan3D-2 --subfolder hunyuan3d-dit-v2-0 --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode ``` Turbo Version ```bash # Hunyuan3D-2mini python3 gradio_app.py --model_path tencent/Hunyuan3D-2mini --subfolder hunyuan3d-dit-v2-mini-turbo --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode --enable_flashvdm # Hunyuan3D-2mv python3 gradio_app.py --model_path tencent/Hunyuan3D-2mv --subfolder hunyuan3d-dit-v2-mv-turbo --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode --enable_flashvdm # Hunyuan3D-2 python3 gradio_app.py --model_path tencent/Hunyuan3D-2 --subfolder hunyuan3d-dit-v2-0-turbo --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode --enable_flashvdm ``` ### API Server You could launch an API server locally, which you could post web request for Image/Text to 3D, Texturing existing mesh, and e.t.c. ```bash python api_server.py --host 0.0.0.0 --port 8080 ``` A demo post request for image to 3D without texture. ```bash img_b64_str=$(base64 -i assets/demo.png) curl -X POST "http://localhost:8080/generate" \ -H "Content-Type: application/json" \ -d '{ "image": "'"$img_b64_str"'", }' \ -o test2.glb ``` ### Blender Addon With an API server launched, you could also directly use Hunyuan3D 2.0 in your blender with our [Blender Addon](blender_addon.py). Please follow our tutorial to install and use. https://github.com/user-attachments/assets/8230bfb5-32b1-4e48-91f4-a977c54a4f3e ### Official Site Don't forget to visit [Hunyuan3D](https://3d.hunyuan.tencent.com) for quick use, if you don't want to host yourself. ## 📑 Open-Source Plan - [x] Inference Code - [x] Model Checkpoints - [x] Technical Report - [x] ComfyUI - [x] Finetuning - [ ] TensorRT Version ## 🔗 BibTeX If you found this repository helpful, please cite our reports: ```bibtex @misc{lai2025hunyuan3d25highfidelity3d, title={Hunyuan3D 2.5: Towards High-Fidelity 3D Assets Generation with Ultimate Details}, author={Tencent Hunyuan3D Team}, year={2025}, eprint={2506.16504}, archivePrefix={arXiv}, primaryClass={cs.CV}, url={https://arxiv.org/abs/2506.16504}, } @misc{hunyuan3d22025tencent, title={Hunyuan3D 2.0: Scaling Diffusion Models for High Resolution Textured 3D Assets Generation}, author={Tencent Hunyuan3D Team}, year={2025}, eprint={2501.12202}, archivePrefix={arXiv}, primaryClass={cs.CV} } @misc{yang2024hunyuan3d, title={Hunyuan3D 1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation}, author={Tencent Hunyuan3D Team}, year={2024}, eprint={2411.02293}, archivePrefix={arXiv}, primaryClass={cs.CV} } ``` ## Community Resources Thanks for the contributions of community members, here we have these great extensions of Hunyuan3D 2.0: - [ComfyUI-3D-Pack](https://github.com/MrForExample/ComfyUI-3D-Pack) - [ComfyUI-Hunyuan3DWrapper](https://github.com/kijai/ComfyUI-Hunyuan3DWrapper) - [Hunyuan3D-2-for-windows](https://github.com/sdbds/Hunyuan3D-2-for-windows) - [📦 A bundle for running on Windows | 整合包](https://github.com/YanWenKun/Hunyuan3D-2-WinPortable) - [Hunyuan3D-2GP](https://github.com/deepbeepmeep/Hunyuan3D-2GP) - [Kaggle Notebook](https://github.com/darkon12/Hunyuan3D-2GP_Kaggle) ## Acknowledgements We would like to thank the contributors to the [Trellis](https://github.com/microsoft/TRELLIS), [DINOv2](https://github.com/facebookresearch/dinov2), [Stable Diffusion](https://github.com/Stability-AI/stablediffusion), [FLUX](https://github.com/black-forest-labs/flux), [diffusers](https://github.com/huggingface/diffusers), [HuggingFace](https://huggingface.co), [CraftsMan3D](https://github.com/wyysf-98/CraftsMan3D), and [Michelangelo](https://github.com/NeuralCarver/Michelangelo/tree/main) repositories, for their open research and exploration. ## Star History