Sheshiyer Hunyuan3D — Image-to-3D Model Generation
Generate 3D models from images using Tencent's Hunyuan3D-2.1 hosted on Hugging Face Spaces. Supports geometry-only and fully textured output with export to multiple 3D formats.
Prerequisites
Ensure gradio_client is installed:
pip install gradio_client
Workflow
Quick Generation (Single Command)
To generate a 3D model from an image, run the bundled script:
# Geometry + Texture (default)
python scripts/hunyuan3d_generate.py --image <path-to-image> --mode full --output ./output/
# Geometry only (faster)
python scripts/hunyuan3d_generate.py --image <path-to-image> --mode shape --output ./output/
Multi-View Generation
When multiple views of the subject are available, provide them for higher quality:
python scripts/hunyuan3d_generate.py \
--front front.png --back back.png --left left.png --right right.png \
--mode full --output ./output/
Quality Presets
| Goal | Flags |
|---|---|
| Quick draft / iteration | --steps 10 --resolution 128 |
| Balanced (default) | --steps 30 --resolution 256 |
| High quality | --steps 50 --resolution 384 |
Export Formats
To specify the output format, use --export-format:
python scripts/hunyuan3d_generate.py --image photo.png --mode full --export-format obj
Supported formats: glb (default), obj, ply, stl.
To include texture in the export, add --export-texture. To simplify the mesh, add --simplify --target-faces 10000.
Script Reference
The generation script is at scripts/hunyuan3d_generate.py. Key arguments:
| Argument | Default | Description |
|---|---|---|
--image |
None | Single input image path |
--front/back/left/right |
None | Multi-view image paths |
--mode |
full | shape (geometry) or full (geometry + texture) |
--steps |
30 | Inference steps (10=Turbo, 20=Fast, 30=Standard) |
--guidance-scale |
5.0 | Guidance scale for generation |
--seed |
1234 | Random seed |
--resolution |
256 | Octree resolution (128=Low, 256=Standard, 384=High) |
--rembg / --no-rembg |
True | Remove image background before generation |
--num-chunks |
8000 | Number of processing chunks |
--export-format |
glb | Output format: glb, obj, ply, stl |
--simplify |
False | Reduce mesh face count |
--export-texture |
False | Include texture in exported file |
--target-faces |
10000 | Target face count when simplifying |
--output |
None | Directory to copy final output to |
Inline Usage (Without Script)
When integrating into other Python code or needing finer control, use gradio_client directly. Refer to references/api_reference.md for the full API endpoint documentation including parameter types, defaults, and return values.
from gradio_client import Client, handle_file
client = Client("tencent/Hunyuan3D-2.1")
# Generate with texture
result = client.predict(
image=handle_file("photo.png"),
steps=30,
guidance_scale=5,
seed=1234,
octree_resolution=256,
check_box_rembg=True,
num_chunks=8000,
randomize_seed=True,
api_name="/generation_all",
)
shape_file, textured_file, html, mesh_stats, seed_used = result
Notes
- The Hugging Face Space may have queue times depending on load. The script blocks until generation completes.
- Single-image input works well for objects with relatively simple geometry. Multi-view input produces better results for complex shapes.
- Background removal (
--rembg) is enabled by default and recommended for most inputs. - GLB format is recommended for web/game use; OBJ for editing in DCC tools like Blender.