Back to Details

tencent-hunyuan3d

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tencent Hunyuan3D

腾讯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).
Hunyuan3D是腾讯推出的生成式3D模型系列，其核心特征是先形状后纹理的两阶段流水线：一个模型从图像（或文本）生成无纹理几何结构，另一个模型为该几何结构赋予材质。该系列涵盖可自行托管的开源权重版本和仅能通过托管API调用的闭源版本。本技能的核心价值在于帮助用户在这两个版本轨道间做出正确选择，并在商用部署前读懂许可证条款。
**以下所有版本、许可证、硬件及访问相关信息均于2026-07-10验证。**这些信息可能随时变化，在依赖前请务必对照官方仓库重新核实。信息标注分为
[fact]
（有官方文档来源）、
[first-party claim]
（腾讯自身基准测试/营销内容，未经过独立验证）或
[heuristic]
（生产实践经验，非官方保障）。

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.
当需求涉及以下内容时，可使用本技能：
  • 从图像或文本提示生成3D物体/资产；
  • 生成3D场景/世界（全景图、可探索环境）——对应HunyuanWorld / HY-World分支；
  • 决定自托管还是托管API，或选择合适的Hunyuan3D版本；
  • 许可证/合规性问题（商用场景、地域限制、月活用户数、署名要求）；
  • 为本地推理或ComfyUI配置GPU规格；
  • 审核或后处理Hunyuan3D的输出结果（拓扑结构、UV展开、PBR贴图）。
请勿将本技能用于2D图像生成（对应HunyuanImage）、视频生成（对应HunyuanVideo）或Hunyuan文本LLM（Hunyuan/Hy3）——这些是独立的模型系列，仅共享“Hunyuan”品牌名称。

The version landscape (verified 2026-07-10)

版本矩阵（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)

轨道A：开源权重、可自托管（从GitHub + Hugging Face下载）

ModelReleasedParams (shape / paint)What it addsLicense
Hunyuan3D-2.0Jan 2025DiT-v2-0 ~1.1B / Paint-v2-0 ~1.3B (+ Delight)Original open two-stage object modelTencent Hunyuan 3D 2.0 Community License
Hunyuan3D-2miniMar 18 2025DiT-v2-mini 0.6BLow-VRAM shape (~5 GB)same 2.0 license
Hunyuan3D-2mvMar 18 2025DiT-v2-mv ~1.1BMulti-view shape input (front+back+sides)same 2.0 license
-Turbo / -Fast + FlashVDMMar 19 2025distilled variants of aboveStep/guidance distillation; fast decodesame 2.0 license
Hunyuan3D-2.1Jun 13–14 2025DiT-v2-1 ~3.0B / Paint-v2-1 ~1.3–2BFirst fully open PBR + full training codeTencent Hunyuan 3D 2.1 Community License
HunyuanWorld-1.0Jul 26 2025—Open scene/world gen: panorama proxy → layered mesh + 3DGS, 360°Tencent Hunyuan community license
HY-World 2.0 / WorldMirror 2.0Apr 16 2026—Text/image/multiview/video → meshes + 3DGS + point clouds; editable, engine-readyopen (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
.
模型发布时间参数规模（形状 / 纹理）新增特性许可证
Hunyuan3D-2.02025年1月DiT-v2-0 ~11亿 / Paint-v2-0 ~13亿（含Delight）初代开源两阶段物体模型腾讯Hunyuan 3D 2.0社区许可证
Hunyuan3D-2mini2025年3月18日DiT-v2-mini 6亿低显存形状模型（约5GB）同2.0许可证
Hunyuan3D-2mv2025年3月18日DiT-v2-mv ~11亿多视角形状输入（正面+背面+侧面）同2.0许可证
-Turbo / -Fast + FlashVDM2025年3月19日上述模型的蒸馏变体步骤/引导蒸馏；快速解码同2.0许可证
Hunyuan3D-2.12025年6月13–14日DiT-v2-1 ~30亿 / Paint-v2-1 ~13-20亿首个完全开源的PBR模型 + 完整训练代码腾讯Hunyuan 3D 2.1社区许可证
HunyuanWorld-1.02025年7月26日—开源场景/世界生成：全景代理→分层网格+3DGS，支持360°视角腾讯Hunyuan社区许可证
HY-World 2.0 / WorldMirror 2.02026年4月16日—文本/图像/多视角/视频→网格+3DGS+点云；可编辑、适配引擎开源（GitHub + HF）
[fact]
Hunyuan3D-2.1是物体生成领域的开源基准版本。当你需要PBR材质且希望获取开源许可证下的完整权重及训练代码时，应选择自托管该版本。来源：GitHub仓库
Tencent-Hunyuan/Hunyuan3D-2.1
、arXiv论文2506.15442。
[fact]
FlashVDM可加速形状解码器：腾讯宣称Lightning Vectset解码器实现了超45倍的速度提升，且Progressive Flow Distillation采样仅需5步（
[first-party claim]
速度提升幅度）。可通过turbo checkpoint或
--enable_flashvdm
参数启用。

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

轨道B：闭源、仅托管API可用（无下载权重，2026-07-10验证）

ModelReleasedDistinguishing capabilityAvailability
Hunyuan3D-2.5Apr 2025~10B params, 1024 geometric resolution, 4K textures, bump maps, "LATTICE" shape model, skeletal skinningTencent Cloud API + 3rd-party hosts
Hunyuan3D-PolyGenJul 8 2025Art-grade topology — clean quad/tri meshes, autoregressive mesh (BPT tokenization), intelligent retopologyAPI / Tencent internal game pipelines
Hunyuan3D-3.0Sep 20253D-DiT "hierarchical sculpting," ~1536³ resolutionTencent Cloud API
Hunyuan3D-3.1later 2025/2026Hosted refinement of 3.0Tencent 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.
模型发布时间核心特性访问渠道
Hunyuan3D-2.52025年4月约100亿参数，1024几何分辨率，4K纹理，凹凸贴图，"LATTICE"形状模型，骨骼蒙皮腾讯云API + 第三方平台
Hunyuan3D-PolyGen2025年7月8日艺术级拓扑结构——干净的四边形/三角形网格，自回归网格（BPT tokenization），智能重拓扑API / 腾讯内部游戏管线
Hunyuan3D-3.02025年9月3D-DiT“分层雕刻”，~1536³分辨率腾讯云API
Hunyuan3D-3.12025年末/2026年基于3.0的托管优化版本腾讯云 + 第三方平台（fal、Replicate等）
[fact]
2.5 / PolyGen / 3.x版本为闭源：仅能通过托管API访问，无法获取权重。腾讯云国际站及面向海外用户的Hunyuan3D API于2025年11月26日上线。若任务同时要求“使用开源权重”和“使用3.0/PolyGen”，则存在矛盾——需向用户指出这一点。来源：腾讯云文档1284/75539；hunyuan3d.cc版本说明；腾讯新闻稿。
[heuristic]
PolyGen专为解决开源2.x版本网格的最大缺陷——拓扑结构而设计。若你遇到的问题是自托管生成的网格为密集三角面片，那么解决方案是使用PolyGen（托管版）或手动重拓扑，而非更换其他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:
  1. 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.
  2. 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.
  3. 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.
这是该模型系列中最关键的生产实践要点。开源权重并非MIT/Apache许可证，而是采用腾讯Hunyuan 3D社区许可证协议（按模型版本区分，例如“TENCENT HUNYUAN 3D 2.1 COMMUNITY LICENSE AGREEMENT”）。
[fact]
2026-07-10已通过
Tencent-Hunyuan/Hunyuan3D-2
和
Hunyuan3D-2.1
仓库中的LICENSE文件验证。
三个常被忽略的限制条款：
  1. 地域限制 
    [fact]
    。许可证授权范围为全球，但不包括欧盟、英国和韩国。禁止在“受限地域”内使用。位于柏林、伦敦或首尔的团队无法依据本协议使用开源权重。这是硬性法律限制，而非偏好——只要用户所在地或目标市场位于这些地区，就必须指出这一点。
  2. 百万月活商用门槛 
    [fact]
    。若在模型发布当日，被许可方提供的产品/服务在前一个日历月的月活跃用户数超过100万，则被许可方必须向腾讯申请单独许可证（发送邮件至hunyuan3d@tencent.com，注明公司名称、行业及使用场景）。月活低于100万时，可在“非受限地域”内免费商用。
  3. 禁止用途 
    [fact]
    。约20条条款中包括：不得用于改进竞品AI模型；不得用于军事用途；不得生成危害未成年人的内容；不得生成选举虚假信息；不得生成恶意软件；不得未披露AI生成内容；不得用于“影响个人安全、权利或福祉的高风险自动化决策”。
署名要求 
[fact]
：分发时需包含NOTICE文件（内容为“Tencent Hunyuan 3D 2.1 is licensed under the Tencent Hunyuan 3D 2.1 Community License Agreement, Copyright © 2025 Tencent.”），且产品需标注“Powered by Tencent Hunyuan”。
[heuristic]
托管API并未消除这些合规问题——只是更换了适用的条款文档。腾讯云及第三方平台（fal、Replicate等）各自有独立的服务条款。不要假设“托管=无限制商用”；需查看具体平台的服务条款，若用户位于欧盟/英国/韩国，使用托管API通常比自托管未获地域授权的开源权重更合规，但仍需确认平台是否允许该用途。当商用部署存在不确定性时，建议用户咨询自身法务团队，不要做出无依据的合规承诺。

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.
[fact]
（arXiv论文2506.15442、Hunyuan3D-2.1）流水线采用模块化设计——你可以单独运行任意一个阶段。
阶段1：形状生成（Hunyuan3D-DiT + ShapeVAE）
  • 输入：单张图像（需去除背景）、多视角图像（2mv）或文本（文本会先转换为图像）。
  • 基于向量集隐空间的流扩散模型生成符号距离/占用场；Marching Cubes算法提取** watertight（无漏洞）**三角形网格。
  • octree_resolution
    是控制几何密度/质量的核心参数。
  • 输出：无纹理网格（GLB/OBJ格式，trimesh对象）。
阶段2：纹理/材质生成（Hunyuan3D-Paint）
  • 输入：阶段1生成的网格（Hunyuan3D自身生成的网格，或你导入的自定义网格）。
  • 网格条件下的多视角扩散模型从多个角度渲染物体（训练时使用512×512分辨率视图），生成视角一致的材质贴图，然后烘焙为UV纹理。
  • [fact]
    2.1版本基于Disney Principled BRDF生成PBR贴图：albedo（反照率，无光照影响，采用光照不变训练策略）、metallic（金属度）和roughness（粗糙度）。它使用3D-aware RoPE保证跨视角一致性。2.0版本的Paint输出更接近烘焙漫反射颜色；2.1是首个开源PBR版本。
[heuristic]
由于阶段2支持任意网格，一个高效工作流是：仅使用Hunyuan3D为现有（手动建模或重拓扑后的）网格添加纹理，或仅用它生成形状，再在其他工具中处理纹理。将两个阶段视为独立工具使用。

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.
[heuristic]
文本转3D内部流程为文本→图像→3D，因此你会在图像步骤失去控制权。只要几何结构重要，就提供自定义参考图像。优质形状输入需满足：
  • 单一、清晰分离的主体，完整物体在画面中，无裁剪；
  • 纯色/可移除背景（流水线会自动去除背景；复杂背景会降低生成质量）；
  • 正面、近似正交视角，光照均匀，无强烈阴影（阴影可能被烘焙到几何结构中）；
  • 若物体的背面或侧面细节重要，使用2mv多视角输入——单张正面图像会迫使模型凭空生成未被看到的面，往往会在凹面、背面细节和薄结构上出错。

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

自托管：硬件与配置（2026-07-10验证）

[fact]
VRAM footprints (from the model READMEs — note the two open lines report slightly different numbers, so plan for the larger):
TaskHunyuan3D-2.0 lineHunyuan3D-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.
[fact]
VRAM占用（来自模型README——注意两个开源系列的数值略有差异，建议按较大值规划）：
任务Hunyuan3D-2.0系列Hunyuan3D-2.1系列
仅形状生成~6GB（2mini约5GB）~10GB
仅纹理生成—~21GB
形状+纹理联合生成~12–16GB~29GB
[heuristic]
实际参考：24GB显存显卡（RTX 3090/4090）可运行2.1版本的形状+纹理生成，但需在阶段间卸载模型，而非同时将两个模型保存在内存中；同时运行需要约29GB显存，即32–48GB显存显卡或分阶段执行并卸载模型。2mini是8GB消费级显卡的选择（仅形状生成）。蒸馏后的Turbo + FlashVDM路径适用于快速迭代，而非追求最高保真度。
[fact]
2.1版本的参考环境：Python 3.10、PyTorch 2.5.1 + CUDA 12.4。配置过程中会编译自定义光栅化器和DifferentiableRenderer / mesh painter（C++/CUDA扩展）——需预留时间用于构建步骤及匹配CUDA工具链。纹理超分需要单独下载Real-ESRGAN权重。仓库中提供Gradio应用（
gradio_app.py
）和REST接口（
/generate
，输入base64图像→输出GLB）。来源：
Hunyuan3D-2.1
README。

ComfyUI

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.
[fact]
（docs.comfy.org，2026-07-10验证）ComfyUI仅原生支持形状/几何生成阶段——
Hunyuan3D-2
、
2mv
和
2mv-turbo
的工作流可生成无纹理GLB文件至
ComfyUI/output/mesh
。纹理/材质生成无原生节点支持。若要在ComfyUI内进行PBR纹理生成，需使用社区封装工具（如ComfyUI-Hunyuan3DWrapper）。若仅使用ComfyUI，需单独规划纹理生成阶段。

Hosted access routes (verified 2026-07-10)

托管访问渠道（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.
  • 腾讯云“Hunyuan 3D APIs”（文档
    1284/75539
    ）——官方渠道；国际站自2025年11月26日上线。支持闭源2.5 / PolyGen / 3.x版本。
  • Hugging Face Space 
    tencent/Hunyuan3D-2.1
    ——开源模型的免费演示，适合快速验证能力，不适合生产级调用量。
  • 第三方平台——fal.ai、Replicate、3D AI Studio、Atlas Cloud等平台将Hunyuan3D封装在自有API后，并提供计费服务。
[fact]
各平台的版本/定价参考（仅供指示，具体以平台为准）：“快速”版本约2–3分钟完成，固定中等多边形预算及~1K纹理；“专业”版本调用完整模型，支持配置多边形数量（~4万–150万）及最高4K PBR纹理。单模型价格约为**$0.02–$0.38**；某积分体系中专业版需60积分（+20积分用于PBR、+20积分用于多视角，上限100），快速版需35积分（+20积分用于PBR，上限55）。所有价格均可能变动——请向用户引用平台实时定价，而非上述数值。

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).
[fact]
开源2.x版本的网格由扩散场的Marching Cubes算法生成。这意味着网格是无漏洞的，但同时密集、均匀三角化、无四边形、缺乏艺术家友好的拓扑结构（无循环边）。UV是为纹理生成自动生成的，并非为手动编辑优化。
[heuristic]
对生产流水线的影响——需规划以下处理步骤：
  • 重拓扑。原始网格不适合绑定骨骼/动画或平滑变形。在动画前需进行重拓扑（手动、自动重拓扑工具，或通过PolyGen处理，该模型专为解决此问题设计）。
  • 网格简化。针对实时场景（游戏/AR/网页），需将密集网格简化至目标三角/多边形数量；建议从高分辨率网格烘焙法线贴图以保留细节。
  • UV重新布局。若需要人工绘制或编辑纹理，而非仅使用自动烘焙的PBR贴图，需重新布局UV。
  • 缩放/方向/原点标准化——生成的资产很少符合你的引擎单位、向上轴或轴心点规范。
  • PBR贴图验证——确认albedo、金属度和粗糙度通道均已导出且分离正确（部分导出路径会合并为漫反射贴图）。

Reviewing generated assets — quality checklist

生成资产审核——质量检查清单

[heuristic]
Before accepting an asset, check:
  1. Silhouette & proportions from all sides (orbit it) — front-only inputs frequently produce a plausible front and a mangled back.
  2. Unseen-face invention — concavities, undercuts, and thin features (straps, handles, hair) are the common failure zone; verify they exist and are solid.
  3. Floaters / disconnected shells / non-manifold artifacts from marching cubes.
  4. 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)?
  5. Topology — acceptable for a static prop as-is; not acceptable for animation without retopology.
  6. PBR correctness — albedo should be lighting-free (no baked highlights or cast shadows); metallic/roughness should read physically (metal vs dielectric).
  7. Texture seams and stretching at UV boundaries; resolution adequacy (1K vs 4K depending on tier and camera proximity).
  8. Scale/orientation normalized to target engine.
[heuristic]
接受资产前需检查：
  1. 轮廓与比例（从所有角度观察）——单视角输入常导致正面合理但背面扭曲。
  2. 未可见面的生成——凹面、下切结构和薄特征（肩带、把手、毛发）是常见失败区域；需验证其存在且结构完整。
  3. Marching Cubes算法导致的漂浮物/分离面片/非流形 artifacts。
  4. 几何密度与需求匹配度——是否远高于场景需求（需简化）或过于粗糙（提高
    octree_resolution
    / 使用2.5/3.0版本）？
  5. 拓扑结构——静态道具可直接使用；动画资产必须重拓扑后才能使用。
  6. PBR正确性——albedo应无光照影响（无烘焙高光或阴影）；金属度/粗糙度应符合物理规律（金属与绝缘体区分）。
  7. UV边界处的纹理接缝与拉伸；纹理分辨率是否足够（根据版本和相机距离选择1K或4K）。
  8. 缩放/方向是否已标准化至目标引擎。

Production decision: open self-host vs hosted commercial

生产决策：开源自托管 vs 托管商用

[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.
[heuristic]
选择开源自托管2.x版本的场景：
  • 你需要高调用量——单资产边际成本趋近于零，优于按调用付费的API；
  • 数据无法离开本地环境（未发布的IP、私有客户资产）；
  • 你需要免费PBR材质及完整流水线的确定性/可集成性；
  • 你需要训练代码（2.1版本提供）以针对特定领域微调；
  • 且——核心前提：你位于非受限地域（非欧盟/英国/韩国）且月活低于100万，或已获得腾讯商用许可证。
[heuristic]
选择托管API的场景：
  • 你需要最高保真度或分辨率（2.5、3.0版本）或干净拓扑结构（PolyGen），而开源权重无法提供；
  • 你无合适GPU或不想维护CUDA/构建工具链；
  • 调用量低或波动大（按调用付费优于闲置GPU成本）；
  • 你位于欧盟/英国/韩国，自托管开源权重不符合地域授权要求（需选择允许该用途的托管平台——仍需查看其服务条款）。
[first-party claim]
根据腾讯自身基准测试，Hunyuan3D-DiT（2.1）在形状指标上优于同类开源模型（Uni3D-T 0.2556 vs TripoSG 0.2506、Step1X-3D 0.2554），且2.1的Paint版本将纹理CLIP-FID从2.0的26.44提升至24.78。这些是厂商自测数据；对“最优”宣称需保持怀疑，实际选型时应使用自有资产测试候选模型，而非依赖排行榜。

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]
需求：某位于非欧盟/英国/韩国的工作室需为手游生成约500个风格化道具网格，带纹理，使用内部流水线，无单资产云费用预算，配备一张24GB显存GPU。
决策与理由：
  • 轨道选择：自托管——高调用量+固定GPU成本使边际成本趋近于0，500个资产若使用API会产生持续账单。
  • 许可证：工作室位于非受限地域且月活远低于100万→可免费商用；需添加NOTICE文件及“Powered by Tencent Hunyuan”标识。
    [fact]
  • 模型选择：Hunyuan3D-2.1——手游需要PBR材质，且需开源权重+代码。在24GB显存显卡上，分阶段运行形状+纹理生成并卸载模型（联合运行需要约29GB显存）。
    [fact]
    /
    [heuristic]
  • 输入策略：为每个道具提供正面参考图像（概念艺术，已去除背景）；对背面细节重要的道具，提供两个视角并使用2mv。
    [heuristic]
  • 迭代方式：使用Turbo/FlashVDM checkpoint快速锁定轮廓和构图，再用完整模型生成最终结果。
    [heuristic]
  • 后处理步骤：将网格简化至手游多边形预算；从高分辨率网格烘焙法线贴图；对需要变形/动画的道具进行重拓扑（或少量通过托管PolyGen处理）；验证albedo/金属度/粗糙度贴图；将缩放/向上轴标准化至引擎规范。
    [heuristic]
预期结果：无漏洞、带PBR纹理的道具，多边形数量可控，无单资产费用，符合许可证要求。
可能的失败模式：单视角输入导致背面几何结构错误（用2mv缓解）；密集三角拓扑无法用于动画道具（重拓扑/PolyGen解决）；参考图像光照强烈导致albedo带有烘焙阴影（使用均匀光照的参考图）。
变体场景：若该工作室位于德国，则完全无法依据社区许可证使用开源权重——必须切换至服务条款允许该用途的托管API，这会改变成本结构和整体方案。
[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]
  • 单视角输入导致背面/侧面几何结构错误→使用2mv或多视角输入。
  • 拓扑结构无法用于动画→重拓扑或使用PolyGen；开源网格本质是Marching Cubes生成的密集三角面片。
    [fact]
  • 同时运行形状+纹理导致VRAM内存不足→分阶段运行并卸载模型，或切换至2mini版本仅生成形状。
    [heuristic]
  • “albedo”中带有烘焙阴影/高光→参考图像存在定向光照；重新拍摄均匀光照的参考图。
    [heuristic]
  • 假设开源=无限制使用→实际为社区许可证：有地域限制（禁止欧盟/英国/韩国）、百万月活门槛、禁止用途条款、署名要求。
    [fact]
  • 假设ComfyUI可生成纹理→原生ComfyUI仅支持几何生成；纹理生成需使用社区封装工具。
    [fact]
  • 混淆版本轨道→2.5/PolyGen/3.x仅API可用；无法下载其权重。
    [fact]

Primary sources (all verified 2026-07-10)

官方来源（均于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.
  • GitHub 
    Tencent-Hunyuan/Hunyuan3D-2
    ——2.0模型库、变体、FlashVDM、VRAM占用信息。
  • GitHub 
    Tencent-Hunyuan/Hunyuan3D-2.1
    ——2.1权重+训练代码、配置说明、VRAM占用信息。
  • 两个仓库中的LICENSE文件——腾讯Hunyuan 3D 2.0 / 2.1社区许可证（地域限制、百万月活、禁止用途、署名要求）。
  • arXiv 2506.15442——Hunyuan3D 2.1技术报告（两阶段架构、PBR/Disney BRDF、基准测试数据）。
  • arXiv 2506.16504——Hunyuan3D 2.5技术报告。
  • GitHub 
    Tencent-Hunyuan/HunyuanWorld-1.0
    和
    Tencent-Hunyuan/HY-World-2.0
    ；arXiv 2507.21809——场景/世界模型。
  • docs.comfy.org Hunyuan3D-2教程——ComfyUI原生仅支持几何生成。
  • 腾讯云“Hunyuan 3D APIs”（文档1284/75539）及腾讯新闻稿——托管API、国际站上线时间（2025年11月26日）。
  • hunyuan3d.cc版本说明；腾讯Hunyuan公告——PolyGen（2025年7月8日）、2.5、3.0/3.1时间线及闭源状态。