> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-es/generacion-3d/hunyuan3d.md).

# Hunyuan3D 2.1

Genera mallas 3D a partir de texto o imágenes con Tencent Hunyuan3D 2.1 en Clore.ai

Hunyuan3D 2.1 de Tencent es un modelo de generación 3D de dos etapas: primero predice la geometría (forma) y luego sintetiza texturas PBR. Acepta tanto prompts de texto como imágenes de referencia como entrada y genera mallas listas para producción en formato GLB, OBJ o PLY. Con más de 3 millones de descargas en HuggingFace, es uno de los modelos de generación 3D de código abierto más adoptados.

{% hint style="success" %}
Todos los ejemplos se ejecutan en servidores GPU alquilados a través de [Marketplace de CLORE.AI](https://clore.ai/marketplace).
{% endhint %}

## Características clave

* **Texto a 3D e imagen a 3D** — ambos modos de entrada en un solo modelo
* **Flujo de trabajo en dos etapas** — generación de geometría seguida de síntesis de texturas PBR
* **Salida de alta fidelidad** — geometría detallada con mapas de albedo, normales y rugosidad
* **Múltiples formatos de exportación** — GLB, OBJ, PLY
* **Interfaz web de Gradio** — interacción basada en navegador, no requiere programación
* **16–24 GB de VRAM** — funciona en RTX 3090 y RTX 4090
* **Más de 3 millones de descargas** en HuggingFace — comunidad activa y actualizaciones continuas

## Requisitos

| Componente | Mínimo         | Recomendado    |
| ---------- | -------------- | -------------- |
| GPU        | RTX 3090 24 GB | RTX 4090 24 GB |
| VRAM       | 16 GB          | 24 GB          |
| RAM        | 16 GB          | 32 GB          |
| Disco      | 50 GB          | 100 GB         |
| CUDA       | 12.8+          | 12.8+          |
| Python     | 3.10           | 3.11           |

**Precios de Clore.ai:** RTX 4090 ≈ $0.14–0.42/h · RTX 3090 ≈ $0.07–0.21/h

## Inicio rápido

### 1. Clonar e instalar

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

# Crear entorno
conda create -n hunyuan3d python=3.10 -y
conda activate hunyuan3d

# Instalar PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128

# Instalar dependencias
pip install -r requirements.txt

# Descargar pesos del modelo (se descargan automáticamente en la primera ejecución, ~15 GB en total)
python -c "from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline; Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')"
```

### 2. Iniciar la interfaz web de Gradio

```bash
python gradio_app.py --port 7860 --share
```

La interfaz proporciona:

* Campo de entrada de texto para generación de texto a 3D
* Carga de imagen para generación de imagen a 3D
* Deslizadores para pasos de inferencia, escala de guía y semilla
* Vista previa del modelo 3D con controles de órbita
* Botones de descarga para GLB/OBJ/PLY

### 3. Generar mediante la API de Python

```python
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
from hy3dgen.texgen import Hunyuan3DPaintPipeline

# Etapa 1: generación de geometría
shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="shapegen",
)
shape_pipeline.to("cuda")

# Generar malla a partir de texto
mesh = shape_pipeline(
    prompt="una espada medieval detallada con mango ornamentado",
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

mesh.export("sword_shape.glb")
```

### 4. Añadir texturas (Etapa 2)

```python
# Etapa 2: síntesis de texturas
texture_pipeline = Hunyuan3DPaintPipeline.from_pretrained(
    "tencent/Hunyuan3D-2",
    subfolder="texgen",
)
texture_pipeline.to("cuda")

textured_mesh = texture_pipeline(
    mesh=mesh,
    prompt="una espada medieval detallada con mango ornamentado",
    num_inference_steps=20,
    seed=42,
)[0]

textured_mesh.export("sword_textured.glb")
```

## Ejemplos de uso

### Generación de imagen a 3D

```python
from PIL import Image

# Cargar imagen de referencia
image = Image.open("reference_chair.png")

# Generar geometría a partir de la imagen
mesh = shape_pipeline(
    image=image,
    num_inference_steps=30,
    guidance_scale=7.5,
    seed=42,
)[0]

# Aplicar textura
textured = texture_pipeline(
    mesh=mesh,
    image=image,
    num_inference_steps=20,
    seed=42,
)[0]

textured.export("chair.glb")
```

### Procesamiento por lotes

```python
from pathlib import Path

prompts = [
    "un coche deportivo rojo, recurso de videojuego low-poly",
    "un cofre del tesoro de madera, material PBR",
    "un casco de ciencia ficción con visor, superficie dura",
]

output_dir = Path("/workspace/3d-output")
output_dir.mkdir(exist_ok=True)

for i, prompt in enumerate(prompts):
    mesh = shape_pipeline(prompt=prompt, num_inference_steps=30, seed=42)[0]
    textured = texture_pipeline(mesh=mesh, prompt=prompt, num_inference_steps=20, seed=42)[0]
    textured.export(str(output_dir / f"asset_{i:03d}.glb"))
    print(f"Generado: asset_{i:03d}.glb — {prompt[:40]}")
```

### Exportar a múltiples formatos

```python
# GLB (recomendado — incluye texturas, formato universal)
textured_mesh.export("model.glb")

# OBJ (con archivo de material MTL)
textured_mesh.export("model.obj")

# PLY (colores de vértices, compatible con nubes de puntos)
textured_mesh.export("model.ply")
```

## Referencia de rendimiento

| GPU      | Geometría (30 pasos) | Textura (20 pasos) | Total  |
| -------- | -------------------- | ------------------ | ------ |
| RTX 4090 | \~20 seg             | \~15 seg           | ≈35 s  |
| RTX 3090 | \~30 s               | \~25 s             | ≈55 s  |
| A100 40G | \~18 seg             | \~12 s             | \~30 s |

## Consejos

* **Elimina los fondos de imagen** antes de imagen a 3D — usa `rembg` para una segmentación limpia
* **Los prompts de texto se benefician de la especificidad** — "una espada medieval low-poly con mango envuelto en cuero" produce mejores resultados que "espada"
* **Reduce `num_inference_steps`** a 15–20 para vistas previas más rápidas durante la iteración
* **Aumenta `guidance_scale`** (8–12) para una mayor fidelidad al prompt a costa de la diversidad
* **GLB es el mejor formato de exportación** — agrupa geometría, texturas y materiales en un solo archivo
* **Usa `--share`** al iniciar Gradio en Clore.ai para acceso remoto desde el navegador
* **Los pesos del modelo son \~15 GB** — asegúrate de tener suficiente espacio en disco antes de la primera ejecución
* **Para recursos de videojuegos**, genera con alta calidad y luego reduce la malla en Blender para niveles LOD

## Solución de problemas

| Problema                                        | Solución                                                                                                           |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `CUDA sin memoria`                              | Usa una RTX 3090 o superior (24 GB). Reduce el tamaño del lote o los pasos de inferencia                           |
| La descarga del modelo se detiene               | Comprueba el espacio en disco. Usa `huggingface-cli download tencent/Hunyuan3D-2` manualmente                      |
| La interfaz de Gradio no es accesible           | Pasa `--share` la opción --share, o reenvía el puerto 7860 desde el panel de Clore.ai                              |
| Calidad de geometría deficiente                 | Aumenta `num_inference_steps` a 40 o más, prueba distintas semillas                                                |
| Artefactos de textura                           | Asegúrate de que la malla de la geometría esté limpia antes de la etapa de textura                                 |
| Errores de importación en una instalación nueva | Ejecuta `pip install -r requirements.txt` de nuevo — algunas dependencias se compilan desde el código fuente       |
| Generación lenta en la primera ejecución        | Es esperado — la compilación del modelo y la carga de pesos se almacenan en caché después de la primera inferencia |

## Recursos

* [Hunyuan3D-2 en GitHub](https://github.com/Tencent/Hunyuan3D-2)
* [Modelo de HuggingFace](https://huggingface.co/tencent/Hunyuan3D-2)
* [Marketplace de CLORE.AI](https://clore.ai/marketplace)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-es/generacion-3d/hunyuan3d.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.