Tencent Hunyuan3D

Hunyuan3D is Tencent's family of generative 3D models. Its defining trait is a two-stage, shape-then-texture pipeline: one model generates untextured geometry from an image (or text), a second model paints materials onto that geometry. The family spans open-weight releases you can self-host and closed tiers available only through a hosted API. Choosing correctly between those two tracks — and reading the license before you ship anything commercial — is the core production judgment this skill supports.

All version, license, hardware, and access facts below were verified 2026-07-10. These are volatile; re-verify against first-party repos before relying on them. Facts are labeled

[fact]

(documented in a primary source),

[first-party claim]

(Tencent's own benchmark/marketing, not independently reproduced), or

[heuristic]

(production judgment, not a documented guarantee).

When this skill applies

Use it when the request involves:

generating a 3D object/asset from an image or text prompt;
generating a 3D scene/world (panorama, explorable environment) — the HunyuanWorld / HY-World branch;
deciding self-host vs hosted API, or which Hunyuan3D tier fits;
license/compliance questions (commercial use, Territory, MAU, attribution);
GPU sizing for local inference or ComfyUI setup;
reviewing or post-processing Hunyuan3D output (topology, UVs, PBR maps).

Do not use it for 2D image generation (that is HunyuanImage), video (HunyuanVideo), or the Hunyuan text LLMs (Hunyuan/Hy3) — those are separate model families that happen to share the "Hunyuan" brand.

The version landscape (verified 2026-07-10)

Two tracks. Getting the track right is the first decision, because it determines cost model, control, and legal footing.

Track A — Open-weight, self-hostable (download from GitHub + Hugging Face)

Model	Released	Params (shape / paint)	What it adds	License
Hunyuan3D-2.0	Jan 2025	DiT-v2-0 ~1.1B / Paint-v2-0 ~1.3B (+ Delight)	Original open two-stage object model	Tencent Hunyuan 3D 2.0 Community License
Hunyuan3D-2mini	Mar 18 2025	DiT-v2-mini 0.6B	Low-VRAM shape (~5 GB)	same 2.0 license
Hunyuan3D-2mv	Mar 18 2025	DiT-v2-mv ~1.1B	Multi-view shape input (front+back+sides)	same 2.0 license
-Turbo / -Fast + FlashVDM	Mar 19 2025	distilled variants of above	Step/guidance distillation; fast decode	same 2.0 license
Hunyuan3D-2.1	Jun 13–14 2025	DiT-v2-1 ~3.0B / Paint-v2-1 ~1.3–2B	First fully open PBR + full training code	Tencent Hunyuan 3D 2.1 Community License
HunyuanWorld-1.0	Jul 26 2025	—	Open scene/world gen: panorama proxy → layered mesh + 3DGS, 360°	Tencent Hunyuan community license
HY-World 2.0 / WorldMirror 2.0	Apr 16 2026	—	Text/image/multiview/video → meshes + 3DGS + point clouds; editable, engine-ready	open (GitHub + HF)

[fact]

Hunyuan3D-2.1 is the reference open baseline for object generation. It is the version to self-host when you need PBR and want everything (weights and training code) under an open license. Sources: GitHub

Tencent-Hunyuan/Hunyuan3D-2.1

, arXiv 2506.15442.

[fact]

FlashVDM accelerates the shape decoder: Tencent reports a Lightning Vectset Decoder with >45x speedup and Progressive Flow Distillation sampling in as few as 5 steps (

[first-party claim]

on the speedup magnitude). Enable via the turbo checkpoints /

--enable_flashvdm

Track B — Closed, hosted API only (no downloadable weights, verified 2026-07-10)

Model	Released	Distinguishing capability	Availability
Hunyuan3D-2.5	Apr 2025	~10B params, 1024 geometric resolution, 4K textures, bump maps, "LATTICE" shape model, skeletal skinning	Tencent Cloud API + 3rd-party hosts
Hunyuan3D-PolyGen	Jul 8 2025	Art-grade topology — clean quad/tri meshes, autoregressive mesh (BPT tokenization), intelligent retopology	API / Tencent internal game pipelines
Hunyuan3D-3.0	Sep 2025	3D-DiT "hierarchical sculpting," ~1536³ resolution	Tencent Cloud API
Hunyuan3D-3.1	later 2025/2026	Hosted refinement of 3.0	Tencent Cloud + hosts (fal, Replicate, etc.)

[fact]

The 2.5 / PolyGen / 3.x tiers are closed-source: accessible only through hosted APIs, not as weights. The Tencent Cloud International Station and Hunyuan3D API for overseas users launched Nov 26 2025. If a task says "use the open weights" and also "use 3.0/PolyGen," that is contradictory — surface it. Sources: Tencent Cloud doc 1284/75539; hunyuan3d.cc version notes; Tencent press.

[heuristic]

PolyGen exists specifically to solve the biggest weakness of the open 2.x meshes: topology. If your blocker is that self-hosted meshes are dense triangle soup, PolyGen (hosted) or a manual retopology pass is the answer — not a different 2.x checkpoint.

The license — read this before any commercial deployment

This is the single most consequential production fact in the family. The open weights are not MIT/Apache. They ship under the Tencent Hunyuan 3D Community License Agreement (versioned per model, e.g. "TENCENT HUNYUAN 3D 2.1 COMMUNITY LICENSE AGREEMENT").

[fact]

Verified 2026-07-10 from the LICENSE files in

Tencent-Hunyuan/Hunyuan3D-2

and

Hunyuan3D-2.1

Three restrictions that routinely surprise people:

Territory exclusion
[fact]
. The license grant is worldwide excluding the European Union, the United Kingdom, and South Korea. Use "outside the Territory" is prohibited. A team in Berlin, London, or Seoul is not licensed to use the open weights under this agreement. This is a hard legal blocker, not a preference — flag it whenever a user's location or target market is in those regions.
1 million MAU commercial gate
[fact]
. If, on the model's release date, the products/services made available by or for the licensee had > 1,000,000 monthly active users in the preceding calendar month, the licensee must request a separate license from Tencent (email hunyuan3d@tencent.com with company name, sector, and use case). Below 1M MAU, commercial use is permitted within the Territory at no charge.
Prohibited uses
[fact]
. Among ~20 clauses: no use to improve competing AI models; no military use; no generating content that harms minors; no election disinformation; no malware; no undisclosed AI-generated content; no "high-stakes automated decisions affecting an individual's safety, rights, or wellbeing."

Attribution
[fact]
: redistribution requires a NOTICE file ("Tencent Hunyuan 3D 2.1 is licensed under the Tencent Hunyuan 3D 2.1 Community License Agreement, Copyright © 2025 Tencent."), and products are expected to be marked "Powered by Tencent Hunyuan."

[heuristic]

The hosted API does not erase these questions — it changes which document governs. Tencent Cloud and third-party hosts (fal, Replicate, etc.) each impose their own Terms of Service. Do not assume "hosted = unrestricted commercial"; check the specific host's ToS, and if a user is in EU/UK/KR, using a hosted API is often the cleaner route than self-hosting weights they aren't Territory-licensed for — but confirm the host permits it. When a commercial deployment is on the line and the facts are ambiguous, tell the user to get their own legal read; do not assert a clearance you cannot source.

How generation actually works (the two-stage pipeline)

[fact]

(arXiv 2506.15442, Hunyuan3D-2.1) The pipeline is deliberately modular — you can run either stage alone.

Stage 1 — Shape (Hunyuan3D-DiT + ShapeVAE):

Input: a single image (background removed), or multi-view images (2mv), or text (which is routed through text-to-image first).
A flow-based diffusion model over a vectset latent produces a signed-distance / occupancy field; marching cubes extracts a watertight triangle mesh.
```
octree_resolution
```
is the primary geometry-density / quality knob.
Output: an untextured mesh (GLB/OBJ, trimesh object).

Stage 2 — Texture / material (Hunyuan3D-Paint):

Input: the mesh from Stage 1 (Hunyuan3D's own, or your own imported mesh).
A mesh-conditioned multi-view diffusion model renders the object from several viewpoints (training used 512×512 views) and generates view-consistent material maps, then bakes them into UV textures.
```
[fact]
```
2.1 produces PBR maps under the Disney Principled BRDF: albedo (light-free, via an illumination-invariant training strategy), metallic, and roughness. It uses a 3D-aware RoPE for cross-view consistency. 2.0's Paint output was closer to baked diffuse color; 2.1 is the first open PBR.

[heuristic]

Because Stage 2 accepts arbitrary meshes, a strong workflow is: use Hunyuan3D only for texturing an existing (hand-modeled or retopologized) mesh, or only for shape and texture elsewhere. Treat the two stages as independent tools.

Input strategy: image beats text for control

[heuristic]

Text-to-3D internally does text→image→3D, so you surrender control at the image step. Feed your own reference image whenever geometry matters. Good shape inputs:

single, clearly separated subject, whole object in frame, not cropped;
plain / removable background (the pipeline runs background removal; a busy background degrades it);
front-facing, roughly orthographic framing, even lighting, minimal harsh shadow (shadows can be baked into geometry);
for objects where the back or sides matter, use 2mv with multiple views — a single front image forces the model to hallucinate the unseen faces, and it often gets concavities, back detail, and thin structures wrong.

Self-hosting: hardware and setup (verified 2026-07-10)

[fact]

VRAM footprints (from the model READMEs — note the two open lines report slightly different numbers, so plan for the larger):

Task	Hunyuan3D-2.0 line	Hunyuan3D-2.1 line
Shape only	~6 GB (2mini ~5 GB)	~10 GB
Texture only	—	~21 GB
Shape + texture combined	~12–16 GB	~29 GB

[heuristic]

Practical reading: a 24 GB card (RTX 3090/4090) runs 2.1 shape and texture if you offload between stages rather than holding both in memory at once; running both simultaneously wants ~29 GB, i.e. a 32–48 GB card or sequential execution with model offloading. 2mini is the choice for 8 GB consumer cards (shape only). The distilled Turbo + FlashVDM path is for fast iteration, not maximum fidelity.

[fact]

Reference environment for 2.1: Python 3.10, PyTorch 2.5.1 + CUDA 12.4. Setup compiles a custom rasterizer and a DifferentiableRenderer / mesh painter (C++/CUDA extensions) — budget time for the build step and a matching CUDA toolchain. Real-ESRGAN weights are fetched separately for texture upscaling. A Gradio app (

gradio_app.py

) and a REST endpoint (

/generate

, base64 image in → GLB out) ship in the repo. Source:

Hunyuan3D-2.1

README.

ComfyUI

[fact]

(docs.comfy.org, verified 2026-07-10) ComfyUI has native support for the shape/geometry stage only — workflows for

Hunyuan3D-2

2mv

, and

2mv-turbo

generate untextured GLB into

ComfyUI/output/mesh

. Texture/material generation is not in the native nodes. For PBR texturing inside ComfyUI, use a community wrapper (e.g. ComfyUI-Hunyuan3DWrapper). Plan the texture stage separately if you are ComfyUI-only.

Hosted access routes (verified 2026-07-10)

Tencent Cloud "Hunyuan 3D APIs" (doc
```
1284/75539
```
) — first-party; International Station live since Nov 26 2025. Backs the closed 2.5 / PolyGen / 3.x tiers.
Hugging Face Space
```
tencent/Hunyuan3D-2.1
```
— a free demo of the open model, good for a quick capability check, not for production volume.
Third-party hosts — fal.ai, Replicate, 3D AI Studio, Atlas Cloud, and others wrap Hunyuan3D behind their own APIs and billing.

[fact]

Tier/pricing signals seen across hosts (indicative, varies by provider): "Rapid" tiers finish in ~2–3 min with fixed mid-range polygon budgets and ~1K textures; "Pro" tiers invoke the full model with configurable polygon counts (~40K–1.5M) and up to 4K PBR. Per-model prices around $0.02–$0.38 were observed; one credit scheme charged Pro 60 credits (+20 PBR, +20 multi-view, cap 100) vs Rapid 35 (+20 PBR, cap 55). Treat all prices as volatile — quote the host's live pricing, never these numbers, to a user.

Mesh output characteristics and required post-processing

[fact]

Open 2.x meshes come from marching cubes over a diffusion field. That means they are watertight but also dense, uniformly-triangulated, non-quad, and lacking artist topology (no edge loops). UVs are auto-generated for texturing, not laid out for hand-editing.

[heuristic]

Consequences for a production pipeline — plan these passes:

Retopology. Raw meshes are unsuitable for rigging/animation or clean deformation. Retopologize (manual, an auto-retopo tool, or route the asset through PolyGen, which was built for exactly this) before animating.
Decimation. For real-time (game/AR/web) budgets, decimate the dense mesh to a target triangle/polygon count; expect to bake normal maps from the high-res mesh to preserve detail.
UV re-layout if a human needs to paint or edit textures, rather than only consuming the auto-baked PBR set.
Scale / orientation / origin normalization — generated assets rarely come in your engine's units, up-axis, or pivot convention.
PBR map validation — confirm albedo, metallic, and roughness channels all exported and are separated correctly (some export paths flatten to diffuse).

Reviewing generated assets — quality checklist

[heuristic]

Before accepting an asset, check:

Silhouette & proportions from all sides (orbit it) — front-only inputs frequently produce a plausible front and a mangled back.
Unseen-face invention — concavities, undercuts, and thin features (straps, handles, hair) are the common failure zone; verify they exist and are solid.
Floaters / disconnected shells / non-manifold artifacts from marching cubes.
Geometry density vs need — is it far denser than the use case warrants (decimate) or too coarse (raise
```
octree_resolution
```
/ use 2.5/3.0)?
Topology — acceptable for a static prop as-is; not acceptable for animation without retopology.
PBR correctness — albedo should be lighting-free (no baked highlights or cast shadows); metallic/roughness should read physically (metal vs dielectric).
Texture seams and stretching at UV boundaries; resolution adequacy (1K vs 4K depending on tier and camera proximity).
Scale/orientation normalized to target engine.

Production decision: open self-host vs hosted commercial

[heuristic]

Self-hosting an open 2.x model wins when:

you generate high volume — marginal cost per asset approaches zero vs per-call API fees;
data cannot leave your environment (unreleased IP, private client assets);
you need PBR at no per-asset cost and full pipeline determinism/integration;
you want the training code (2.1 ships it) to fine-tune on a domain;
and — the gating condition — you are inside the Territory (not EU/UK/KR) and under 1M MAU, or have Tencent's commercial license.

[heuristic]

A hosted API wins when:

you need peak fidelity or resolution (2.5, 3.0) or clean topology (PolyGen) that the open weights don't provide;
you have no suitable GPU or don't want to maintain the CUDA/build toolchain;
volume is low or spiky (pay-per-use beats idle GPU);
you are in EU/UK/KR and self-hosting the open weights is not Territory-licensed (use a host that permits your use — and still check its ToS).

[first-party claim]

On Tencent's own benchmarks, Hunyuan3D-DiT (2.1) edges comparable open models on shape metrics (Uni3D-T 0.2556 vs TripoSG 0.2506, Step1X-3D 0.2554) and 2.1's Paint improves texture CLIP-FID to 24.78 from 2.0's 26.44. These are vendor-reported; treat "best" claims skeptically and, for a real selection, run your own assets through candidates rather than trusting a leaderboard.

Complete example (labeled example, not a required formula)

Intent: A studio outside the EU/UK/KR needs ~500 stylized prop meshes for a mobile game, textured, on an in-house pipeline, no per-asset cloud fee, budget for one 24 GB GPU.

Decision & reasoning:

Track: self-host — high volume + fixed GPU makes marginal cost ~0, and 500 assets would be a recurring API bill.
License: studio is in-Territory and well under 1M MAU → free commercial use; add the NOTICE file and "Powered by Tencent Hunyuan" mark.
```
[fact]
```
Model: Hunyuan3D-2.1 — need PBR for the game's lighting, want the open weights + code. On a 24 GB card, run shape then texture sequentially with offload (combined would want ~29 GB).
```
[fact]
```
/
```
[heuristic]
```
Input: provide a front reference image per prop (concept art), background removed; for props with important back detail, capture two views and use 2mv.
```
[heuristic]
```
Iterate with the Turbo/FlashVDM checkpoint to lock silhouette and framing cheaply, then re-run the full model for the final.
```
[heuristic]
```
Post-process each asset: decimate to the mobile poly budget; bake normals from the dense mesh; retopologize any prop that will deform/animate (or send those few through hosted PolyGen); validate the albedo/metallic/roughness set; normalize scale/up-axis to the engine.
```
[heuristic]
```

Expected result: watertight, PBR-textured props at controlled poly counts, no per-asset fee, license-clean.

Likely failure modes: hallucinated back faces on single-view props (mitigate with 2mv); dense triangle topology unusable for the few animated props (retopo/PolyGen); albedo with baked shadows if lighting in the reference was harsh (use flat, even reference lighting).

Variation: the same studio in Germany cannot use the open weights under the Community License at all — it must switch to a hosted API whose ToS permits the use, changing the economics and the whole plan.

[fact]

Common failure modes (summary)

Back/side geometry wrong from single-view input → use 2mv or multiple views.
Topology unusable for animation → retopologize or use PolyGen; the open meshes are marching-cubes triangle soup by design.
```
[fact]
```
VRAM OOM running shape+texture together → run stages sequentially with offload, or drop to 2mini for shape.
```
[heuristic]
```
Baked shadows/highlights in "albedo" → the input reference had directional lighting; re-shoot flat.
```
[heuristic]
```
Assuming open = unrestricted → it is the Community License: Territory-limited (no EU/UK/KR), 1M-MAU gate, prohibited-use clauses, attribution.
```
[fact]
```
Assuming ComfyUI gives you textures → native ComfyUI is geometry-only; texture needs a community wrapper.
```
[fact]
```
Confusing tracks → 2.5/PolyGen/3.x are API-only; you cannot download their weights.
```
[fact]
```

Primary sources (all verified 2026-07-10)

GitHub
```
Tencent-Hunyuan/Hunyuan3D-2
```
— 2.0 model zoo, variants, FlashVDM, VRAM.
GitHub
```
Tencent-Hunyuan/Hunyuan3D-2.1
```
— 2.1 weights + training code, setup, VRAM.
LICENSE files in both repos — Tencent Hunyuan 3D 2.0 / 2.1 Community License (Territory, 1M MAU, prohibited uses, attribution).
arXiv 2506.15442 — Hunyuan3D 2.1 technical report (two-stage architecture, PBR / Disney BRDF, benchmark numbers).
arXiv 2506.16504 — Hunyuan3D 2.5 technical report.

GitHub

Tencent-Hunyuan/HunyuanWorld-1.0

and

Tencent-Hunyuan/HY-World-2.0

; arXiv 2507.21809 — world/scene models.

docs.comfy.org Hunyuan3D-2 tutorial — ComfyUI native geometry-only support.
Tencent Cloud "Hunyuan 3D APIs" (doc 1284/75539) and Tencent press releases — hosted API, International Station launch (Nov 26 2025).
hunyuan3d.cc version notes; Tencent Hunyuan announcements — PolyGen (Jul 8 2025), 2.5, 3.0/3.1 timeline and closed-source status.

tencent-hunyuan3d

NPX Install

Tags

SKILL.md Content