Hugging Face's logo

tencent
/
Hunyuan3D-2

Image-to-3D
Hunyuan3D-2
Diffusers
Safetensors
English
Chinese
text-to-3d
Model card Files Community
54
Hunyuan3D-2 / README.md
nielsr's picture
nielsr HF Staff
Update model card to Hunyuan3D 2.5
a9cbd5d verified
preview code
|
raw
history blame
18.2 kB
metadata
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. For code and more details on how to use it, refer to the Github repository.

πŸ”₯ News

Join our Wechat and Discord 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 | | Hunyuan3D-Paint-v2-1 | Texture Generation Model | 2025-06-13 | 1.3B | Download |

Hunyuan3D-2mini Series

Model Description Date Size Huggingface
Hunyuan3D-DiT-v2-mini-Turbo Step Distillation Version 2025-03-19 0.6B Download
Hunyuan3D-DiT-v2-mini-Fast Guidance Distillation Version 2025-03-18 0.6B Download
Hunyuan3D-DiT-v2-mini Mini Image to Shape Model 2025-03-18 0.6B Download

Hunyuan3D-2mv Series

Model Description Date Size Huggingface
Hunyuan3D-DiT-v2-mv-Turbo Step Distillation Version 2025-03-19 1.1B Download
Hunyuan3D-DiT-v2-mv-Fast Guidance Distillation Version 2025-03-18 1.1B Download
Hunyuan3D-DiT-v2-mv Multiview Image to Shape Model 2025-03-18 1.1B Download

Hunyuan3D-2 Series

Model Description Date Size Huggingface
Hunyuan3D-DiT-v2-0-Turbo Step Distillation Model 2025-03-19 1.1B Download
Hunyuan3D-DiT-v2-0-Fast Guidance Distillation Model 2025-02-03 1.1B Download
Hunyuan3D-DiT-v2-0 Image to Shape Model 2025-01-21 1.1B Download
Hunyuan3D-Paint-v2-0 Texture Generation Model 2025-01-21 1.3B Download
Hunyuan3D-Paint-v2-0-Turbo Distillation Texure Model 2025-04-01 1.3B Download
Hunyuan3D-Delight-v2-0 Image Delight Model 2025-01-21 1.3B Download

πŸ€— 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:

Install Requirements

Please install Pytorch via the official site. Then install the other requirements via

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:

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, which you could save to glb/obj (or other format) file.

For Hunyuan3D-Paint, do the following:

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 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 App in your own computer via:

Standard Version

# 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

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

python api_server.py --host 0.0.0.0 --port 8080

A demo post request for image to 3D without texture.

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. 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 for quick use, if you don't want to host yourself.

πŸ“‘ Open-Source Plan

  • Inference Code
  • Model Checkpoints
  • Technical Report
  • ComfyUI
  • Finetuning
  • TensorRT Version

πŸ”— BibTeX

If you found this repository helpful, please cite our reports:

@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:

Acknowledgements

We would like to thank the contributors to the Trellis, DINOv2, Stable Diffusion, FLUX, diffusers, HuggingFace, CraftsMan3D, and Michelangelo repositories, for their open research and exploration.

Star History

Star History Chart