Hunyuan3D 2.1 Documentation

Run the API server using api_server.py. You can specify the host and port via command-line arguments.

Command:

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

Once the API server is running, you can access interactive documentation to test endpoints and view parameter details.

1. Start the server:

   python api_server.py

2. Open your browser to:
   • Swagger UI: http://localhost:8081/docs (for interactive testing)
   • ReDoc: http://localhost:8081/redoc (for structured documentation)

The rendering scripts require Blender 4.1. You must install opencv, OpenEXR, and Imath using Blender's internal Python environment.

Example for macOS:

/Applications/Blender.app/Contents/Resources/4.1/python/bin/python3.11 -m pip install OpenEXR Imath opencv-python

To launch the container for the first time, use docker run with GPU support and port mapping for the Gradio app. This command initializes the container named hy3d21 and starts the Gradio application on port 7860. Once running, you can access the interface at http://127.0.0.1:7860 from your host machine.

docker run -it --name hy3d21 -p 7860:7860 --gpus all hunyuan3d21 python gradio_app.py --port 7860

Before running inference, you must manually download the RealESRGAN weight into the ckpt folder using wget.

wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P ckpt

The repository includes several scripts for testing the API implementation:

• Comprehensive testing: python test_generate_endpoint.py tests all parameters.
• Simple image testing: python simple_test.py <path_to_image> (e.g., python simple_test.py assets/example_images/004.png).
• Command-line testing: ./curl_example.sh uses curl to interact with the endpoints.

Use the render/render.py script via Blender to convert 3D formats to PLY, render conditional images for DiT training, or render PBR materials and conditional signals (normals/position).

To convert formats and render images (includes --geo_mode):

$BLENDER_PATH -b -P render/render.py -- \
    --object ${INPUT_FILE} --geo_mode --resolution 512 \
    --output_folder $OUTPUT_FOLDER

To render PBR materials and conditional signals (normals/position), run the same command but remove the --geo_mode flag.

The pipeline.sh script automates the full data processing workflow. Before running, modify the first four variables in pipeline.sh:

1. INPUT_FILE: Path to each 3D data file.
2. OUTPUT_FOLDER: Overall path for the output dataset.
3. NAME: Naming convention for output paths.
4. BLENDER_PATH: Path to the Blender executable.

Execute the pipeline with:

bash pipeline.sh

The API provides interactive documentation interfaces via FastAPI:

• Swagger UI: Accessible at http://localhost:7860/docs. Use this to test endpoints directly in your browser.
• ReDoc: Accessible at http://localhost:7860/redoc. Provides an alternative structured documentation view.

After the initial setup, you can manage the hy3d21 container using the following commands:

• Start the container: Use docker start -a hy3d21 to restart the existing container in attached mode.
• Stop the container: Use docker stop hy3d21 to halt the running container.

To set up Hunyuan3D 2.1, ensure you are using Python 3.10. The installation involves installing PyTorch with CUDA 12.4 support, installing project dependencies, compiling custom rasterizers and differentiable renderers, and downloading the Real-ESRGAN checkpoint.

VRAM Requirements:

• Shape generation: 10 GB
• Texture generation: 21 GB
• Combined (Shape + Texture): 29 GB

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

cd hy3dpaint/custom_rasterizer
pip install -e .
cd ../..
cd hy3dpaint/DifferentiableRenderer
bash compile_mesh_painter.sh
cd ../..

wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P hy3dpaint/ckpt

To perform quick inference using a reference image (e.g., image.png), run the provided minimal demo script. The output will be saved as demo.glb.

Hardware Requirement: It is recommended to use a GPU with at least 10GB VRAM.

python3 minimal_demo.py