Hunyuan3D-2: Tencent open source high-resolution 3D model generation tool

General Introduction

Hunyuan3D-2 is an open source project developed by Tencent, aiming to generate high-resolution 3D models from text or images. It consists of two core components: shape generation model (Hunyuan3D-DiT) and texture generation model (Hunyuan3D-Paint). Users can enter text descriptions or upload images to generate 3D digital assets with detailed textures. The tool is freely available on GitHub with code and pre-trained models, with the latest version updated on 3/18/2025. It supports multiple models, including fast and mini versions for different devices.Hunyuan3D-2 is widely used in game development, digital art and research.

Function List

• Supports 3D model generation from text, user inputs description to generate corresponding geometry.
• Supports generating 3D models from images and generating 3D assets with textures after uploading images.
• Provides high-resolution output with crisp model details and vibrant texture colors.
• Includes a shape generation model (Hunyuan3D-DiT), which is responsible for generating the underlying geometry.
• Includes texture generation model (Hunyuan3D-Paint) to add high resolution texture to the model.
• Support multi-view generation (Hunyuan3D-2mv) to optimize the model from multiple perspectives.
• A mini version of the model (Hunyuan3D-2mini) is provided, with only 0.6 billion parameters and faster operation.
• Supports a fast version of the model (Fast), which halves the inference time and makes it more efficient.
• Blender can be integrated to generate and edit 3D models directly through the plug-in.
• Open source code and models that users can freely download and modify.

Using Help

Hunyuan3D-2 is a powerful tool that requires some hardware and programming basics. The following is a detailed installation and usage guide to help users get started quickly.

Installation process

1. Preparation of hardware and software environments
   • Requires NVIDIA GPU with CUDA support and at least 6GB (Mini) or 12GB (Standard) of video memory.
   • Install Python 3.9 or later.
   • Install Git for downloading code.
2. Download code and models
   • Runs in the terminal:

     git clone https://github.com/Tencent/Hunyuan3D-2.git
     cd Hunyuan3D-2
     

   • Download the pre-trained model from Hugging Face:

     huggingface-cli download tencent/Hunyuan3D-2 --local-dir . /weights
     

3. Installation of dependencies
   • Install basic dependencies:

     pip install -r requirements.txt
     

   • Installs additional modules for texture generation:

     cd hy3dgen/texgen/custom_rasterizer
     python3 setup.py install
     cd ... /... /...
     cd hy3dgen/texgen/differentiable_renderer
     python3 setup.py install
     

   • Optional Flash Attention acceleration can be installed:

     pip install ninja
     pip install git+https://github.com/Dao-AILab/flash-attention.git@v2.6.3
     

4. Verify Installation
   • Run the sample code:

     python minimal_demo.py
     

   • If the model is successfully exported, the installation is complete.

Main Functions

1. Generation of 3D models from images

• move::
  • Prepare a picture (e.g. demo.png), placed in the assets Folder.
  • Generate the base shape:

    from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
    from PIL import Image
    pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')
    image = Image.open('assets/demo.png')
    mesh = pipeline(image=image, num_inference_steps=30)[0]
    mesh.export('output.glb')
    

  • Add texture:

    from hy3dgen.texgen import Hunyuan3DPaintPipeline
    pipeline = Hunyuan3DPaintPipeline.from_pretrained('tencent/Hunyuan3D-2')
    mesh = pipeline(mesh, image=image)
    mesh.export('textured.glb')
    

• in the end: Generate a 3D model with textures, save it as .glb Documentation.

2. Generating 3D models from text

• move::
  • Install the text-to-image module (HunyuanDiT):

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

  • Run the code:

    from hy3dgen.text2image import HunyuanDiTPipeline
    from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
    t2i = HunyuanDiTPipeline('Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled')
    i23d = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')
    image = t2i('a cute rabbit')
    mesh = i23d(image, num_inference_steps=30)[0]
    mesh.export('rabbit.glb')
    

• in the end: Generate 3D models from text.

3. Using the Gradio interface

• move::
  • Run the Gradio application:

    python3 gradio_app.py --model_path tencent/Hunyuan3D-2 --subfolder hunyuan3d-dit-v2-0 --texgen_model_path tencent/Hunyuan3D-2
    

  • Open your browser and visit the prompted local address.
  • Upload an image or enter text and click Generate.
• in the end: Generate models through a web interface without writing code.

4. Use of API services

• move::
  • Start the API server:

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

  • Send a request to generate a model:

    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 test.glb
    

• in the end: Generate 3D models via API.

5. Use of the Blender plug-in

• mounting::
  • downloading blender_addon.py Documentation.
  • Open Blender and install and enable it in Edit > Preferences > Plugins.
• manipulate::
  • Start the API server (see above).
  • Find "Hunyuan3D-2" in the Blender sidebar.
  • Enter text or upload an image and click Generate.
• in the end: Generate and edit models directly in Blender.

Featured Function Operation

Multi-view generation (Hunyuan3D-2mv)

• Use the command:

pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2mv', subfolder='hunyuan3d-dit-v2-mv')
mesh = pipeline(image=Image.open('assets/demo.png'))[0]
mesh.export('mv_model.glb')

• Ideal for scenes that require accurate modeling from multiple angles.

Rapid generation (Hunyuan3D-2mini)

• Use the command:

pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2mini', subfolder='hunyuan3d-dit-v2-mini')
mesh = pipeline(image=Image.open('assets/demo.png'))[0]
mesh.export('mini_model.glb')

• Fast and suitable for low configuration devices.

caveat

• Ensure that the GPU driver is compatible with the CUDA version to avoid runtime errors.
• align num_inference_steps Parameters can be optimized for generation quality.
• If you have problems, ask for help at GitHub Issues or Discord (https://discord.gg/dNBrdrGGMa).

application scenario

1. game development
   Developers can use it to quickly generate in-game character or prop models, reducing manual modeling time.
2. digital art
   Artists generate 3D artwork from text or images for creative or NFT production.
3. product design
   Designers upload product images to generate 3D models for displaying or testing prototypes.
4. Educational research
   Students and researchers use it to explore techniques for AI-generated 3D and to validate diffusion models.

QA

1. What are the minimum hardware requirements?
   The Mini version requires 6GB of video memory and the Standard version requires 12GB with a recommended NVIDIA GPU.
2. Is it commercially available?
   The open source version is for non-commercial use only. For commercial use, please contact for authorization.
3. How long does it take to generate a model?
   About 30 seconds for the fast version and 1-2 minutes for the standard version, depending on hardware and settings.