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_resolutionis 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.0andTencent-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.