Tencent Hunyuan3d

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 [email protected] 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.