# Hunyuan3D-2 API: Image-to-Mesh (HuggingFace Space)

Free, no-account image-to-3D generation via Tencent's Hunyuan3D-2 on HuggingFace Spaces.

## Install

```bash
python3 -m ensurepip --upgrade
python3 -m pip install gradio_client trimesh
```

## Generate mesh from image

```python
from gradio_client import Client, handle_file

c = Client("tencent/Hunyuan3D-2")
img = handle_file("/path/to/image.jpg")

job = c.submit(
    image=img,
    caption=None,           # optional text prompt
    mv_image_front=None,
    mv_image_back=None,
    mv_image_left=None,
    mv_image_right=None,
    steps=30,
    guidance_scale=5.0,
    seed=1234,
    octree_resolution=256,
    check_box_rembg=True,    # auto-remove background
    num_chunks=8000,
    randomize_seed=True,
    api_name="/shape_generation"
)

result = job.result(timeout=300)   # ~8-15 seconds
# result[0] = {'value': '/tmp/.../white_mesh.glb', '__type__': 'update'}
# result[2] = mesh stats (faces, vertices, timing)
# result[3] = seed used
```

## Convert GLB → STL for printing

```python
import trimesh

mesh = trimesh.load("/tmp/.../white_mesh.glb", force='mesh')
print(f"Faces: {len(mesh.faces)}, Vertices: {len(mesh.vertices)}")
print(f"Watertight: {mesh.is_watertight}")
mesh.export("/path/to/output.stl")
```

## Pitfalls

- **Not watertight by default**: Hunyuan3D-2 outputs a visual mesh (not manifold). For printing, run through Bambu Studio's mesh repair (right-click → repair) or use trimesh's `mesh.fill_holes()` / `mesh.remove_unreferenced_vertices()`.
- **Scale is unitless**: The mesh comes out in abstract units. Scale to mm in your slicer or with `mesh.apply_scale(target_height / mesh.extents[2])`.
- **API may change**: HuggingFace Spaces can be paused or updated. If the space is down, check `tencent/Hunyuan3D-2` for a new space URL.
- **Size limits**: HF Spaces have memory limits. Images >2MB may cause OOM. Resize to ~512x512 first if needed.
- **Gradio version mismatch**: If you get `gradio.data_classes.FileData() argument after ** must be a mapping, not str`, upgrade: `python3 -m pip install gradio_client --upgrade`.

## When to use this vs. ASCII-STL builder

- **Simple boxes, cases, mechanical parts** → ASCII-STL builder (exact control, parametric, watertight)
- **Organic shapes, characters, avatars** → Hunyuan3D-2 (free, fast, photo-to-mesh)