OneClick3D

Generate textured 3D models from a single image or a text prompt — in one click, on Windows, with zero setup.
Powered by Tencent Hunyuan3D 2.1 · Bundled as a portable installer · No Python, no CLI, no headaches.

⬇️ Download latest release · Quick Start · Features · Benchmarks · API · Troubleshooting · FAQ

🇬🇧 English · 🇫🇷 Français

🎯 Why OneClick3D?

Most open-source 3D generators require a full Python toolchain, manual CUDA setup, half a day of dependency fighting, and another half-day of HuggingFace token configuration. OneClick3D ships a single Windows installer and gets you generating textured 3D meshes in minutes — not days.

	Vanilla Hunyuan3D	OneClick3D
Python install	manual (3.10+)	✅ embedded 3.12
CUDA / Torch wheels	manual	✅ pre-bundled
Model downloads	manual `git lfs`	✅ auto from HuggingFace
Web UI	manual launch	✅ desktop launcher + browser
Low-VRAM offloading	code-level config	✅ slider (MMGP 1-5)
REST API	not included	✅ FastAPI + key auth
OpenAI-compatible API	❌	✅ optional wrapper
Languages	EN/ZH	✅ EN / FR / ZH
Process safety	orphan GPU processes	✅ Windows Job Object

🚀 Quick Start

  1. Download   →   Hunyuan3D2_Setup.exe  (from the Releases page)
  2. Install    →   double-click, accept GPU detection
  3. Launch     →   Desktop shortcut "Hunyuan3D2 OneClick3D"
  4. First run  →   ~31 GB models auto-download (one-time, resumable)
  5. Create     →   drop an image or type a prompt → textured 3D mesh

💡 The installer itself is ~7 GB. Model weights are pulled from HuggingFace Hub on first launch so you always get the latest revisions.

⬇️ Get the latest installer →

✨ Features

Generation pipelines

Pipeline	Input	Output	Typical time (RTX 4080)
Image → 3D	PNG · JPG · WEBP	textured GLB / OBJ / STL / PLY	30–120 s
Text → 3D	natural language prompt	textured 3D mesh	2–5 min
Shape only	image	untextured mesh	20–60 s
Texture pass	existing mesh	PBR maps	~60 s

Model variants

Model	Size	VRAM	Best for
Hunyuan3D-2.1 (default)	~13 GB	8 GB+	General purpose, best quality
Hunyuan3D-2.0	~26 GB	12 GB+	Original full model
Hunyuan3D-2.0-mini	~22 GB	6 GB+	Low-VRAM GPUs
Hunyuan3D-2.0-mv	~9 GB	8 GB+	Multi-view variant
HunyuanDiT-1.1	~14 GB	8 GB+	Text-to-image stage of Text→3D
DINOv2-giant	~4 GB	2 GB+	Visual encoder for texturing

Export formats

GLB (recommended) · OBJ + MTL · STL (3D-print ready) · PLY (vertex colors) · FBX (via Blender) · ZIP (batch bundle)

Productivity features

Click to expand the full feature list

Generation Presets — save / load parameter sets (steps, seed, CFG, octree, etc.)
Prompt Enhancer — AI-powered prompt rewriting for richer outputs
Batch Generation — queue multiple prompts, processed sequentially
Generation Gallery — auto-saved thumbnails of all your creations
LRU Cache — repeated prompts return instantly from SHA256-keyed cache
Real-time GPU Monitor — VRAM, temperature, utilization in the UI
Smart Memory Manager — OOM prevention with emergency recovery
MMGP Off-loading — 5 profiles, automatic model offloading for low-VRAM GPUs
Background Removal — automatic subject isolation, no manual masking
Multi-view consistency — 6-view rendering for clean textures from every angle
PBR Materials — albedo + roughness + metallic maps
i18n — full English / French / Chinese UI
Self-updater — UPDATE.bat pulls the latest code over Git

Under the hood

┌─────────────────────────────────────────────────────────────────┐
│  Desktop Launcher (PySide6)  →  configures + spawns the server  │
└─────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────┐
│  FastAPI (REST)  ‖  Gradio 4.x (Web UI)  ‖  Three.js 3D viewer  │
└─────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────┐
│  Model Worker  →  Memory Manager  →  hy3dshape + hy3dpaint      │
│  (background)     (VRAM guardrails)   (DiT flow matching + PBR) │
└─────────────────────────────────────────────────────────────────┘
                                ↓
┌─────────────────────────────────────────────────────────────────┐
│  PyTorch 2.x  ·  CUDA 12.9  ·  xformers  ·  FlashVDM            │
│  Embedded Python 3.12  ·  Windows Job Object (orphan-safe)      │
└─────────────────────────────────────────────────────────────────┘

💻 System Requirements

Component	Minimum	Recommended
OS	Windows 10 x64 (1903+)	Windows 11
GPU	NVIDIA RTX 2060 (8 GB)	NVIDIA RTX 3080 (12+ GB)
Driver	CUDA 12.x (Game Ready 535+)	Latest Game Ready / Studio
RAM	16 GB	32 GB
Disk	SSD, 30 GB app + 31 GB models	NVMe SSD, 120+ GB free
Internet	Required on first launch	50+ Mbps for faster downloads

VRAM usage by MMGP profile

Profile	VRAM	Speed	Strategy
1	~6 GB	🐢 Slow	Aggressive offloading, CPU pinned memory
3	~8 GB	🚗 Medium	Balanced offloading
5 (default)	~10 GB	🚀 Fast	Minimal offloading, 2.2 GB budget

❗ AMD / Intel GPUs are not supported. Hunyuan3D requires CUDA for its diffusion + flow-matching kernels.

📊 Benchmarks

Indicative timings on representative hardware (Image→3D, 30 steps, octree 256, texture on):

GPU	VRAM	Profile	Shape	Texture	Total
RTX 4090	24 GB	5	~25 s	~45 s	~70 s
RTX 4080	16 GB	5	~35 s	~55 s	~90 s
RTX 3090	24 GB	5	~40 s	~65 s	~105 s
RTX 3080	10 GB	3	~55 s	~85 s	~140 s
RTX 3060	12 GB	3	~80 s	~120 s	~200 s
RTX 2060	8 GB	1	~140 s	~210 s	~350 s

Numbers vary with image complexity, driver version, background apps, and thermal headroom. Text→3D adds ~30–60 s for the HunyuanDiT image generation step.

📖 User Guide

Installation

Download the installer from Releases.
Run Hunyuan3D2_Setup.exe — Windows SmartScreen may warn (click More info → Run anyway).
The installer auto-detects an NVIDIA GPU via nvidia-smi.
Choose install location (default C:\Program Files\Hunyuan3D2).
Optionally create a Desktop shortcut.
The first-run screen explains the model-download process.

Launching

Option A — Desktop launcher (recommended)

Double-click Hunyuan3D2 OneClick3D.
The PySide6 GUI opens with configuration tabs.
Click Start → Gradio web server launches → browser opens http://localhost:8080.

Option B — Direct batch file

Run RUN.bat (English) or 启动.bat (Chinese) from the install folder.

Image → 3D in 60 seconds

1.  Open the "Image to 3D" tab
2.  Drop an image (PNG · JPG · WEBP)
3.  Steps: 30   |   CFG: 6.0   |   Seed: -1   |   Octree: 256
4.  Click "Generate Shape"     → mesh appears in the 3D viewer
5.  Click "Generate Texture"   → PBR textures applied
6.  Export → GLB

Text → 3D

Open the Text to 3D tab.
Enter a description (e.g. "a red sports car, 3D model, white background").
(Optional) Click Enhance Prompt for an AI rewrite.
Click Generate — pipeline runs HunyuanDiT → background removal → shape → texture.
Total time: 2–5 min depending on GPU.

Generation presets

Action	How
Save	configure parameters → click 💾 → name it
Load	pick from the dropdown → fields auto-fill
Delete	select → click 🗑️

Built-ins: default, high_quality, fast_preview. Stored as JSON in Hunyuan3D-2.1/presets/.

Launcher configuration

Tab	Options
General Settings	HTTP proxy, working directory
Hunyuan3D-2.1	Model path, subfolder, port, MMGP profile, language, Text→3D toggle, Flash VDM, texture toggle, compile mode, low-VRAM mode

Saved to launcher_config.json, persists between sessions.

🔌 API Reference

A FastAPI REST server runs alongside the Gradio UI.

Endpoints

Method	Path	Description
`POST`	`/generate`	Synchronous 3D generation from a base64 image
`POST`	`/send`	Async generation — returns a task UID
`GET`	`/status/{uid}`	Poll task progress
`GET`	`/health`	Service health check
`GET`	`/docs`	Interactive Swagger UI

Example

curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key-here" \
  -d '{
    "image": "data:image/png;base64,iVBOR...",
    "texture": true,
    "seed": 42,
    "steps": 30,
    "guidance_scale": 6.0,
    "octree_resolution": 256
  }'

Python client

import base64, requests

with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

r = requests.post(
    "http://localhost:8080/generate",
    headers={"X-API-Key": "your-key-here"},
    json={"image": f"data:image/png;base64,{img_b64}", "texture": True, "steps": 30},
    timeout=600,
)
with open("out.glb", "wb") as f:
    f.write(r.content)

Authentication & rate limiting

A first key is auto-generated on startup (printed in the console).
Pass it via X-API-Key header or ?api_key= query parameter.
Per-IP rate limiting; stale entries are pruned every 5 minutes.

OpenAI-compatible endpoint

An optional wrapper exposes an OpenAI-style API for tools that already speak that format. See GUIDE_OPENAI.md.

🔧 Building from Source

Prerequisites

Inno Setup 6.x — Download and add iscc.exe to PATH.
PowerShell 5.1+ (built into Windows 10/11).
~25 GB free disk space on the build drive.

Build steps

cd installer

# 1) Build staging (~1 min, ~10.5 GB output)
powershell -ExecutionPolicy Bypass -File build_staging.ps1

# 2) Compile installer (~15–25 min with LZMA2)
iscc installer.iss

Output → installer/Output/Hunyuan3D2_Setup.exe.

What is excluded from the installer

build_staging.ps1 strips, by design:

All HuggingFace models (~88 GB) — auto-downloaded on first launch
Generated outputs (save_dir/, generated_gallery/)
Python bytecode (__pycache__/, *.pyc)
User data (prompt_history.json, custom presets)

Customizing the installer

Setting in `installer.iss`	Default	Description
`DefaultDirName`	`{autopf}\Hunyuan3D2`	Install location
`Compression`	`lzma2/ultra64`	Switch to `lzma2/normal` for ~2× faster build
`PrivilegesRequired`	`admin`	Set to `lowest` for per-user install
`DiskSliceSize`	2.1 GB	Max size per slice file

🗂️ Project Structure

Click to expand the full tree

.
├── README.md                          # This file
├── .gitignore
├── installer/
│   ├── build_staging.ps1              # Robocopy staging builder
│   ├── installer.iss                  # Inno Setup 6.x script
│   ├── first_run.bat                  # Post-install info screen
│   └── BUILD_README.md
│
└── Hunyuan3D2_WinPortable/
    ├── RUN.bat                        # English launcher
    ├── 启动.bat                        # Chinese launcher
    ├── UPDATE.bat                     # Git-based self-updater
    ├── assets/branding/               # Icons, logos, banner
    │
    ├── WinScripts-GUI/
    │   ├── py/launcher.en.py          # PySide6 GUI launcher (EN)
    │   ├── py/launcher.zh.py          # PySide6 GUI launcher (ZH)
    │   └── bat/                       # Launcher batch files
    │
    └── Hunyuan3D-2.1/
        ├── gradio_app.py              # Main web UI
        ├── memory_manager.py          # GPU VRAM manager
        ├── model_worker.py            # Background model inference
        ├── error_handler.py           # Structured errors + i18n
        ├── api_server.py              # FastAPI REST server
        ├── api_auth.py                # API key auth + rate limiter
        ├── api_models.py              # Pydantic v2 request/response
        ├── cache_manager.py           # LRU gen cache (SHA256)
        ├── validators.py              # Input validation
        ├── i18n.py                    # Internationalization (EN/FR/ZH)
        ├── presets_manager.py         # JSON presets (path-traversal-safe)
        ├── text2image.py              # HunyuanDiT text-to-image
        ├── openai_integration.py      # OpenAI API compatibility
        ├── prompt_enhancer.py         # AI prompt improvement
        ├── logger_utils.py            # Logging w/ stream capture
        ├── constants.py               # API metadata
        ├── hy3dshape/                 # Tencent shape pipeline
        │   ├── pipelines.py           # DiT flow-matching pipeline
        │   ├── rembg.py               # Background removal
        │   └── utils/utils.py         # smart_load_model (auto-DL)
        └── hy3dpaint/                 # Tencent PBR texture pipeline
            ├── textureGenPipeline.py
            ├── hunyuanpaintpbr/       # Diffusion-based PBR painting
            └── DifferentiableRenderer/

🛠️ Troubleshooting

The installer says "No NVIDIA GPU detected"

The installer runs nvidia-smi. If it fails:

Update your NVIDIA driver to 535+ (Game Ready or Studio).
Reboot to apply driver changes.
Verify in PowerShell: nvidia-smi. If it isn't found, your driver is broken or missing.
You can still click Yes to install, but inference will not work.

First launch is stuck downloading models

The core models total ~31 GB. At 50 Mbps this is ~80 minutes.
The download is resumable — if you close the app, it picks up where it left off.
Behind a corporate proxy? Set the proxy in the launcher's General Settings tab.
Check Hunyuan3D-2.1/logs/ for HuggingFace Hub progress.

Out of Memory (OOM) error

In order, try:

Lower the MMGP profile to 3 or 1 in the launcher.
Enable Low VRAM mode.
Reduce octree resolution to 256.
Disable texture generation for a first pass, then re-texture later.
Close other GPU-intensive apps (browsers with hardware accel, Discord overlay, OBS…).

CUDA path issues on Windows

Run Hunyuan3D2_WinPortable/run_fix_cuda_path.bat — it repairs the embedded CUDA paths for this install.

Port 8080 already in use

Change the port in the launcher's Hunyuan3D-2.1 tab. The Gradio UI and FastAPI server share the same port.

SmartScreen blocks the installer

This is expected for unsigned installers. Click More info → Run anyway. The installer is fully open-source — read installer/installer.iss if you want to audit before running.

How do I update?

Run UPDATE.bat. It pulls the latest code via Git. Model weights stay put — no re-download.

🗺️ Roadmap

Have an idea? Open an issue — feature requests are welcome.

🤝 Contributing

Contributions are welcome. The smoothest path:

Open an issue first to discuss substantial changes.
Fork the repo, branch from main.
Keep PRs focused — one feature/fix per PR.
For UI strings, update all three language files in i18n.py.
Test on a real Windows install before pushing — many bugs only appear in the bundled runtime.

Small, well-described PRs get merged fastest.

❓ FAQ

Q: Can I use this commercially? A: The Hunyuan3D model is under the Tencent Hunyuan 3D Community License, which has territorial and commercial-use conditions. Read it in full before commercial deployment. The OneClick3D wrapper code (installer, launcher, memory manager, API layer) is MIT.

Q: Does this send any data to Tencent or Anthropic or anyone else? A: No telemetry. Model weights are pulled from HuggingFace Hub on first launch; after that, all inference runs locally on your GPU.

Q: Which export format should I use? A: GLB for most cases (Blender, Unity, Unreal, glTF web viewers). OBJ for legacy pipelines. STL for 3D printing (geometry only, no textures).

Q: Can I run the API without the Gradio UI? A: Yes — set the launcher to API-only mode, or call the FastAPI endpoints directly. Gradio just shares the same port.

Q: My output mesh has holes / weird topology. A: Increase the octree resolution (384 or 512), use a cleaner reference image (front-facing, neutral background), and rerun. For production assets, plan on a quick cleanup pass in Blender.

Q: Will you support AMD / Intel / Mac? A: Hunyuan3D currently relies on CUDA kernels — see the roadmap. A ROCm or Metal port would require upstream changes.

🙏 Credits

Tencent Hunyuan3D — Core AI model, shape & texture pipelines
MMGP — Memory management & GPU offloading
Gradio — Web UI framework
FastAPI — REST API
HuggingFace — Model hosting, transformers, diffusers
Inno Setup — Windows installer toolchain
OneClick3D — Windows portable, installer, launcher GUI, memory manager, API layer, i18n, error handling

📄 License

Hunyuan3D 2.1 model: Tencent Hunyuan 3D Community License
OneClick3D wrapper code (installer, launcher, memory manager, API layer): MIT

If OneClick3D saves you a day of setup, please consider ⭐ starring the repo — it really helps.

OneClick3D — 🇫🇷 Version Française

Générez des modèles 3D texturés à partir d'une image ou d'un texte — en un clic, sous Windows, sans aucune installation.
Propulsé par Tencent Hunyuan3D 2.1 · Installeur portable · Sans Python, sans ligne de commande.

🇬🇧 Read in English · ⬇️ Télécharger la dernière version

🎯 Pourquoi OneClick3D ?

La plupart des générateurs 3D open-source nécessitent une chaîne Python complète, une configuration CUDA manuelle, une demi-journée de bataille avec les dépendances et encore une demi-journée pour configurer le token HuggingFace. OneClick3D livre un seul installeur Windows et vous fait générer des maillages 3D texturés en quelques minutes — pas en plusieurs jours.

	Hunyuan3D natif	OneClick3D
Installation Python	manuelle (3.10+)	✅ Python 3.12 embarqué
Wheels CUDA / Torch	manuelles	✅ pré-installées
Téléchargement des modèles	`git lfs` manuel	✅ auto via HuggingFace
Interface web	lancement manuel	✅ lanceur bureau + navigateur
Déchargement faible-VRAM	configuration code	✅ curseur (MMGP 1-5)
API REST	non incluse	✅ FastAPI + clé d'authentification
API compatible OpenAI	❌	✅ wrapper optionnel
Langues	EN / ZH	✅ EN / FR / ZH
Sécurité processus	processus GPU orphelins	✅ Windows Job Object

🚀 Démarrage Rapide

  1. Téléchargez   →   Hunyuan3D2_Setup.exe  (page Releases)
  2. Installez     →   double-clic, validez la détection GPU
  3. Lancez        →   raccourci "Hunyuan3D2 OneClick3D"
  4. 1er démarrage →   ~31 Go de modèles auto-téléchargés (une fois)
  5. Créez         →   image ou prompt → maillage 3D texturé

💡 L'installeur fait ~7 Go. Les poids des modèles sont récupérés depuis HuggingFace Hub au premier lancement pour garantir les dernières versions.

⬇️ Télécharger →

✨ Fonctionnalités

Pipelines de génération

Pipeline	Entrée	Sortie	Temps typique (RTX 4080)
Image → 3D	PNG · JPG · WEBP	GLB / OBJ / STL / PLY texturé	30–120 s
Texte → 3D	prompt en langage naturel	maillage 3D texturé	2–5 min
Forme seule	image	maillage non-texturé	20–60 s
Passe texture	maillage existant	cartes PBR	~60 s

Variantes de modèles

Modèle	Taille	VRAM	Idéal pour
Hunyuan3D-2.1 (défaut)	~13 Go	8 Go+	Usage général, meilleure qualité
Hunyuan3D-2.0	~26 Go	12 Go+	Modèle complet original
Hunyuan3D-2.0-mini	~22 Go	6 Go+	GPU avec peu de VRAM
Hunyuan3D-2.0-mv	~9 Go	8 Go+	Variante multi-vues
HunyuanDiT-1.1	~14 Go	8 Go+	Étape texte→image de Texte→3D
DINOv2-giant	~4 Go	2 Go+	Encodeur visuel pour textures

Formats d'export

GLB (recommandé) · OBJ + MTL · STL (impression 3D) · PLY (couleurs de sommets) · FBX (via Blender) · ZIP (lot complet)

Fonctionnalités de productivité

Cliquez pour voir la liste complète

Préréglages — sauvegardez / chargez des jeux de paramètres
Améliorateur de prompts — réécriture IA pour de meilleurs résultats
Génération par lots — empilez plusieurs prompts
Galerie — miniatures auto-sauvegardées de toutes vos créations
Cache LRU — prompts répétés retournés instantanément (clé SHA256)
Moniteur GPU temps réel — VRAM, température, utilisation dans l'UI
Gestionnaire mémoire intelligent — prévention OOM avec récupération d'urgence
Déchargement MMGP — 5 profils, automatique pour GPU faible-VRAM
Suppression de fond — isolation auto du sujet
Cohérence multi-vues — 6 vues pour des textures propres sous tous angles
Matériaux PBR — cartes albedo + rugosité + métallique
i18n — UI complète EN / FR / ZH
Auto-mise à jour — UPDATE.bat récupère le dernier code via Git

💻 Configuration Requise

Composant	Minimum	Recommandé
OS	Windows 10 x64 (1903+)	Windows 11
GPU	NVIDIA RTX 2060 (8 Go)	NVIDIA RTX 3080 (12+ Go)
Pilote	CUDA 12.x (Game Ready 535+)	Dernier Game Ready / Studio
RAM	16 Go	32 Go
Disque	SSD, 30 Go app + 31 Go modèles	SSD NVMe, 120+ Go libre
Internet	Requis au 1er lancement	50+ Mbps

Utilisation VRAM par profil MMGP

Profil	VRAM	Vitesse	Stratégie
1	~6 Go	🐢 Lent	Déchargement agressif, mémoire CPU épinglée
3	~8 Go	🚗 Moyen	Déchargement équilibré
5 (défaut)	~10 Go	🚀 Rapide	Déchargement minimal, budget 2.2 Go

❗ Les GPU AMD / Intel ne sont pas supportés. Hunyuan3D nécessite les kernels CUDA pour ses pipelines.

📊 Benchmarks

Temps indicatifs (Image→3D, 30 étapes, octree 256, texture activée) :

GPU	VRAM	Profil	Forme	Texture	Total
RTX 4090	24 Go	5	~25 s	~45 s	~70 s
RTX 4080	16 Go	5	~35 s	~55 s	~90 s
RTX 3090	24 Go	5	~40 s	~65 s	~105 s
RTX 3080	10 Go	3	~55 s	~85 s	~140 s
RTX 3060	12 Go	3	~80 s	~120 s	~200 s
RTX 2060	8 Go	1	~140 s	~210 s	~350 s

Les chiffres varient selon la complexité de l'image, la version du pilote, les apps en arrière-plan et la marge thermique. Texte→3D ajoute ~30–60 s pour l'étape image (HunyuanDiT).

📖 Guide Utilisateur

Installation

Téléchargez l'installeur depuis Releases.
Lancez Hunyuan3D2_Setup.exe — Windows SmartScreen peut avertir (Informations complémentaires → Exécuter quand même).
L'installeur vérifie le GPU NVIDIA via nvidia-smi.
Choisissez le dossier (défaut : C:\Program Files\Hunyuan3D2).
Optionnel : créer un raccourci Bureau.
L'écran de 1er lancement explique le téléchargement des modèles.

Lancement

Option A — Lanceur Bureau (recommandé)

Double-cliquez Hunyuan3D2 OneClick3D.
L'interface PySide6 s'ouvre avec ses onglets.
Cliquez Start → serveur Gradio → navigateur sur http://localhost:8080.

Option B — Fichier batch direct

Lancez RUN.bat (anglais) ou 启动.bat (chinois).

Image → 3D en 60 secondes

1.  Onglet "Image to 3D"
2.  Déposez une image (PNG · JPG · WEBP)
3.  Steps : 30   |   CFG : 6.0   |   Seed : -1   |   Octree : 256
4.  Cliquez "Generate Shape"     → maillage dans le visualiseur 3D
5.  Cliquez "Generate Texture"   → textures PBR appliquées
6.  Exportez → GLB

Texte → 3D

Onglet Text to 3D.
Saisissez une description (ex : « une voiture de sport rouge, modèle 3D, fond blanc »).
(Optionnel) Cliquez Améliorer le prompt pour une réécriture IA.
Cliquez Generate — pipeline : HunyuanDiT → suppression de fond → forme → texture.
Temps total : 2–5 min selon le GPU.

Préréglages

Action	Comment
Sauvegarder	configurez → 💾 → nommez
Charger	sélectionnez dans le menu → champs remplis
Supprimer	sélectionnez → 🗑️

Intégrés : default, high_quality, fast_preview. JSON dans Hunyuan3D-2.1/presets/.

Configuration du lanceur

Onglet	Options
Paramètres Généraux	Proxy HTTP, répertoire de travail
Hunyuan3D-2.1	Chemin modèle, sous-dossier, port, profil MMGP, langue, toggle Texte→3D, Flash VDM, toggle texture, compilation, mode faible VRAM

Sauvegardé dans launcher_config.json, persiste entre sessions.

🔌 Référence API

Serveur REST FastAPI exécuté en parallèle de l'UI Gradio.

Points d'accès

Méthode	Chemin	Description
`POST`	`/generate`	Génération 3D synchrone depuis image base64
`POST`	`/send`	Génération asynchrone — renvoie un UID
`GET`	`/status/{uid}`	Progression de la tâche
`GET`	`/health`	Vérification de santé
`GET`	`/docs`	Swagger UI interactif

Exemple

curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: votre-clé-ici" \
  -d '{
    "image": "data:image/png;base64,iVBOR...",
    "texture": true,
    "seed": 42,
    "steps": 30,
    "guidance_scale": 6.0,
    "octree_resolution": 256
  }'

Client Python

import base64, requests

with open("input.png", "rb") as f:
    img_b64 = base64.b64encode(f.read()).decode()

r = requests.post(
    "http://localhost:8080/generate",
    headers={"X-API-Key": "votre-clé-ici"},
    json={"image": f"data:image/png;base64,{img_b64}", "texture": True, "steps": 30},
    timeout=600,
)
with open("out.glb", "wb") as f:
    f.write(r.content)

Authentification & limitation de débit

Une première clé est auto-générée au démarrage (affichée dans la console).
Passez-la via l'en-tête X-API-Key ou le paramètre ?api_key=.
Limitation par IP ; les entrées périmées sont nettoyées toutes les 5 minutes.

Endpoint compatible OpenAI

Un wrapper optionnel expose une API au format OpenAI. Voir GUIDE_OPENAI.md.

🔧 Compilation depuis les Sources

Prérequis

Inno Setup 6.x — Télécharger et ajouter iscc.exe au PATH.
PowerShell 5.1+ (intégré à Windows 10/11).
~25 Go d'espace libre sur le lecteur de compilation.

Étapes

cd installer

# 1) Construire le staging (~1 min, ~10.5 Go en sortie)
powershell -ExecutionPolicy Bypass -File build_staging.ps1

# 2) Compiler l'installeur (~15–25 min avec LZMA2)
iscc installer.iss

Sortie → installer/Output/Hunyuan3D2_Setup.exe.

Ce qui est exclu de l'installeur

build_staging.ps1 exclut intentionnellement :

Tous les modèles HuggingFace (~88 Go) — auto-téléchargés au 1er lancement
Sorties générées (save_dir/, generated_gallery/)
Bytecode Python (__pycache__/, *.pyc)
Données utilisateur (prompt_history.json, préréglages perso)

Personnalisation

Paramètre dans `installer.iss`	Défaut	Description
`DefaultDirName`	`{autopf}\Hunyuan3D2`	Emplacement d'installation
`Compression`	`lzma2/ultra64`	Passer à `lzma2/normal` pour ~2× plus rapide
`PrivilegesRequired`	`admin`	`lowest` pour installation par utilisateur
`DiskSliceSize`	2.1 Go	Taille max par fichier slice

🛠️ Dépannage

L'installeur dit « No NVIDIA GPU detected »

L'installeur exécute nvidia-smi. En cas d'échec :

Mettez à jour le pilote NVIDIA en 535+ (Game Ready ou Studio).
Redémarrez.
Vérifiez dans PowerShell : nvidia-smi. S'il est introuvable, le pilote est cassé ou absent.
Vous pouvez cliquer Oui pour installer quand même, mais l'inférence ne fonctionnera pas.

Le 1er lancement est bloqué sur le téléchargement

Les modèles totalisent ~31 Go. À 50 Mbps cela prend ~80 min.
Le téléchargement est reprenable — fermer l'app n'efface pas le progrès.
Derrière un proxy d'entreprise ? Configurez-le dans l'onglet Paramètres Généraux.
Consultez Hunyuan3D-2.1/logs/ pour le progrès HuggingFace Hub.

Erreur Out of Memory (OOM)

Dans l'ordre :

Baissez le profil MMGP à 3 ou 1 dans le lanceur.
Activez le mode faible VRAM.
Réduisez la résolution octree à 256.
Désactivez la génération de texture pour une première passe.
Fermez les autres apps gourmandes en GPU (navigateurs accélérés, overlay Discord, OBS…).

Problèmes de chemin CUDA sous Windows

Lancez Hunyuan3D2_WinPortable/run_fix_cuda_path.bat — il répare les chemins CUDA embarqués pour votre installation.

Port 8080 déjà utilisé

Changez le port dans l'onglet Hunyuan3D-2.1 du lanceur. L'UI Gradio et le serveur FastAPI partagent le même port.

SmartScreen bloque l'installeur

Attendu pour un installeur non-signé. Cliquez Informations complémentaires → Exécuter quand même. L'installeur est entièrement open-source — lisez installer/installer.iss pour auditer avant exécution.

Comment mettre à jour ?

Lancez UPDATE.bat. Il récupère le dernier code via Git. Les poids restent — pas de re-téléchargement.

🗺️ Roadmap

Une idée ? Ouvrez une issue — les demandes de fonctionnalités sont bienvenues.

🤝 Contribution

Les contributions sont bienvenues. Le chemin le plus simple :

Ouvrez d'abord une issue pour discuter des changements importants.
Forkez le repo, branchez depuis main.
PRs focalisées — une fonctionnalité/correction par PR.
Pour les chaînes UI, mettez à jour les trois fichiers de langue dans i18n.py.
Testez sur une vraie installation Windows avant de pousser.

Les petites PRs bien décrites sont fusionnées le plus vite.

❓ FAQ

Q : Puis-je l'utiliser commercialement ? R : Le modèle Hunyuan3D est sous la Licence Communautaire Tencent Hunyuan 3D, qui comporte des conditions territoriales et d'usage commercial. Lisez-la complètement avant tout déploiement commercial. Le code wrapper OneClick3D (installeur, lanceur, gestionnaire mémoire, couche API) est sous MIT.

Q : Est-ce que ça envoie des données à Tencent, Anthropic, ou n'importe qui ? R : Aucune télémétrie. Les poids sont téléchargés depuis HuggingFace Hub au 1er lancement ; ensuite, toute l'inférence tourne localement sur votre GPU.

Q : Quel format d'export utiliser ? R : GLB pour la plupart des cas (Blender, Unity, Unreal, web glTF). OBJ pour pipelines classiques. STL pour l'impression 3D (géométrie seule, sans textures).

Q : Puis-je lancer l'API sans l'UI Gradio ? R : Oui — passez le lanceur en mode API seule, ou appelez directement les endpoints FastAPI. Gradio partage juste le port.

Q : Mon maillage a des trous / une topologie étrange. R : Augmentez la résolution octree (384 ou 512), utilisez une image de référence plus propre (face, fond neutre), relancez. Pour des assets de production, prévoyez une passe de nettoyage dans Blender.

Q : Supporterez-vous AMD / Intel / Mac ? R : Hunyuan3D dépend des kernels CUDA — voir la roadmap. Un portage ROCm ou Metal nécessiterait des changements en amont.

🙏 Crédits

Tencent Hunyuan3D — Modèle IA, pipelines de formes et textures
MMGP — Gestion mémoire et déchargement GPU
Gradio — Framework d'interface web
FastAPI — API REST
HuggingFace — Hébergement, transformers, diffusers
Inno Setup — Toolchain de l'installeur Windows
OneClick3D — Portable Windows, installeur, lanceur GUI, gestionnaire mémoire, couche API, i18n, gestion d'erreurs

📄 Licence

Modèle Hunyuan3D 2.1 : Licence Communautaire Tencent Hunyuan 3D
Code wrapper OneClick3D (installeur, lanceur, gestionnaire mémoire, couche API) : MIT

Si OneClick3D vous fait gagner une journée de configuration, pensez à ⭐ mettre une étoile au repo — ça aide énormément.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
Hunyuan3D2_WinPortable		Hunyuan3D2_WinPortable
docs		docs
installer		installer
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

OneClick3D

🎯 Why OneClick3D?

🚀 Quick Start

✨ Features

Generation pipelines

Model variants

Export formats

Productivity features

Under the hood

💻 System Requirements

VRAM usage by MMGP profile

📊 Benchmarks

📖 User Guide

Installation

Launching

Image → 3D in 60 seconds

Text → 3D

Generation presets

Launcher configuration

🔌 API Reference

Endpoints

Example

Python client

Authentication & rate limiting

OpenAI-compatible endpoint

🔧 Building from Source

Prerequisites

Build steps

What is excluded from the installer

Customizing the installer

🗂️ Project Structure

🛠️ Troubleshooting

🗺️ Roadmap

🤝 Contributing

❓ FAQ

🙏 Credits

📄 License

OneClick3D — 🇫🇷 Version Française

🎯 Pourquoi OneClick3D ?

🚀 Démarrage Rapide

✨ Fonctionnalités

Pipelines de génération

Variantes de modèles

Formats d'export

Fonctionnalités de productivité

💻 Configuration Requise

Utilisation VRAM par profil MMGP

📊 Benchmarks

📖 Guide Utilisateur

Installation

Lancement

Image → 3D en 60 secondes

Texte → 3D

Préréglages

Configuration du lanceur

🔌 Référence API

Points d'accès

Exemple

Client Python

Authentification & limitation de débit

Endpoint compatible OpenAI

🔧 Compilation depuis les Sources

Prérequis

Étapes

Ce qui est exclu de l'installeur

Personnalisation

🛠️ Dépannage

🗺️ Roadmap

🤝 Contribution

❓ FAQ

🙏 Crédits

📄 Licence

About

Resources

Uh oh!

Stars

Packages