Hunyuan Image to 3D

What it is

Hunyuan Image to 3D takes a single image and turns it into a textured 3D model - a GLB file you can drop straight into Blender, Unity, a game engine, or a web viewer. It's the core node of the ComfyUI-Hunyuan3D-v3 pack, and the one most people install it for: you've got a character sheet, a product shot, a concept image, and you want an actual mesh instead of a flat picture.

The thing to get straight before you wire anything up: this node doesn't run any 3D model on your own GPU. It calls Tencent Cloud's Hunyuan 3D Global API v3, a paid cloud endpoint, and waits for the result. That's a different animal from Tencent's open-weight Hunyuan3D 2.0/2.1 checkpoints that people self-host locally - same lab, same brand, but this pack is API-first and billed per call (roughly $0.10–0.60 a generation per the author's own numbers). If you wanted something free and local, this isn't it; if you want quality 3D without owning the compute for it, this is the trade you're making.

How it works

Under the hood it's a straightforward request/poll loop: your image gets uploaded to Tencent's endpoint along with your generation settings, and the node then waits - up to max_wait_time seconds - for the job to finish server-side before pulling down the resulting GLB. The README puts real generations at roughly 2–5 minutes each, so this is not a fast node; it's closer in feel to submitting a render job than to a normal ComfyUI step.

Inputs and outputs

You'll set these on basically every run:

• image - the source picture. A clean subject on a simple background tends to convert better than a busy scene, though the node itself doesn't do any background removal for you.
• enable_pbr - toggles physically-based rendering materials on the output mesh (default off). Turn it on if you need the model to look right under real lighting in a game engine or renderer; leave it off for a faster, simpler mesh.
• face_count - polygon budget, from 40,000 up to 1,500,000 (default 500,000). Higher counts mean more geometric detail and a bigger file; there's no reason to max this out unless you actually need dense geometry.
• generate_type - Normal, LowPoly, Geometry, or Sketch. Normal is the default full-detail mode; LowPoly is worth trying if you're targeting a real-time engine and don't want to decimate the mesh yourself afterward.
• polygon_type - triangle or quad. Triangles are the safe default for most downstream tools; quads matter if you're planning to do further sculpting or retopology work in a DCC app that prefers them.
• max_wait_time - how long (60–3600s, default 600s) the node will keep polling before giving up. Given the README's own 2–5-minute estimate per image, the default should cover a normal run with headroom, but push it up if you're generating something more complex.
• config - the HUNYUAN_CONFIG from a Hunyuan Config node upstream. You can't run this without it.

Output is a single model_path - a plain string pointing at the saved GLB (the README puts these under ComfyUI/models/3d_models/), not a native 3D/mesh data type. Wire that string into a Hunyuan 3D Model Preview node to load it in ComfyUI, or just grab the file directly off disk for anything else.

Install

Via ComfyUI Manager: search "Hunyuan 3D", install, restart. Manually:

cd ComfyUI/custom_nodes
git clone https://github.com/exedesign/Hunyuan-3D-v3.git
cd Hunyuan-3D-v3
pip install -r requirements.txt

You'll also need a Hunyuan Config node feeding this one - see that node's page for getting Tencent Cloud API keys set up, which is honestly the fiddlier half of getting this pack running.

Troubleshooting

A ResourceInsufficient error means your Tencent Cloud account is out of credit or the Hunyuan 3D service hasn't been activated - check the console balance and top up ($10+ is the README's own recommendation) rather than assuming the node is broken. If a run stalls out and hits max_wait_time without finishing, that's usually just a slow generation on Tencent's end; bump the value up before assuming something failed. And if you're running this on a platform that also enforces its own job timeout on top of the node's max_wait_time - comfy.icu's default is 5 minutes per run - make sure that outer timeout is raised past whatever you set here, or the platform will kill the job before this node's own wait logic ever gets the chance to.