suvadityamuk/Hunyuan3D-2.1-diffusers-3d

Hunyuan3D-2.1 (shape) for diffusers-3d

tencent/Hunyuan3D-2.1 converted into a diffusers-3d pipeline: ordinary Diffusers and Transformers component folders plus the object3d_model_index.json sidecar that the package's auto-loader validates before downloading anything. Nothing here requires remote code.

Install

pip install git+https://github.com/suvadityamuk/diffusers-3d.git
pip install "git+https://github.com/suvadityamuk/diffusers-3d.git#subdirectory=packages/diffusers-3d"

diffusers-3d runs every network in plain PyTorch on CPU or GPU. Rendering Gaussian splats needs the optional gsplat backend; the PBR-textured mesh for TRELLIS.2 needs CuMesh (see the package docs).

Usage

import torch
from diffusers_3d import AutoPipelineForImageTo3D, ImageCondition

pipeline = AutoPipelineForImageTo3D.from_pretrained("suvadityamuk/Hunyuan3D-2.1-diffusers-3d", dtype=torch.float16).to("cuda")
mesh = pipeline(ImageCondition(image=rgba), generator=torch.Generator("cuda").manual_seed(0)).objects[0]

rgba is a (4, H, W) tensor in [0, 1] whose alpha channel masks the object; the pipeline crops and pads it as the released code does. This is the shape stage (hunyuan3d-dit-v2-1); the result is an untextured MeshAsset.

Components

Folder	Class
image_encoder	transformers.Dinov2Model
scheduler	diffusers_3d.families.hunyuan3d.scheduler.Hunyuan3DFlowMatchEulerDiscreteScheduler
transformer	diffusers_3d.families.hunyuan3d.models.Hunyuan3DDiTModel
vae	diffusers_3d.families.hunyuan3d.vae.Hunyuan3DShapeVAE

Provenance

Converted with diffusers-3d-convert-hunyuan3d from diffusers-3d 0.1.0.dev0; the package's family README lists the pinned upstream revisions and how the conversion maps each tensor. Parity tests against the pinned upstream code are part of the package test suite.

License and attribution

Tencent Hunyuan 3D 2.1 is licensed under the Tencent Hunyuan 3D 2.1 Community License Agreement, Copyright © 2025 Tencent. All Rights Reserved. The trademark rights of "Tencent Hunyuan" are owned by Tencent or its affiliate.

This repository redistributes modified Tencent Hunyuan 3D 2.1 works: diffusers-3d converted the released weights into Diffusers component folders (parameters renamed and the ShapeVAE point-cloud encoder dropped; weight values unchanged). The license, including its Acceptable Use Policy and the use restrictions of its Sections 5(a) and 5(b), applies to everyone who uses these files; read LICENSE-TENCENT-HUNYUAN-3D-2.1 and NOTICE before use. The license does not apply in the European Union, the United Kingdom, or South Korea, and products above 1 million monthly active users need a separate license from Tencent. This repository and diffusers-3d are not affiliated with, sponsored, or endorsed by Tencent.