tencent-hunyuan3d — Claude Code skill: what it does, how to install
tencent-hunyuan3d is a Claude Code skill that guides 3D mesh generation using Tencent's model family. It handles model selection, hardware sizing, and license verification.
MIT 152 installs ★ 252 updated 2026-07-14
npx skills add calesthio/generative-media-skills --skill tencent-hunyuan3d -a claude-codeWhat tencent-hunyuan3d does
This skill guides image-to-3D and text-to-3D workflows across the Tencent Hunyuan3D ecosystem. The models follow a two-stage shape-then-texture pipeline: one network produces untextured geometry, and a second pass paints materials. It helps you navigate the choice between open-weight models for self-hosting like Hunyuan3D-2.1 and closed hosted API tiers like PolyGen or 3.1.
For local inference, it assists with GPU memory planning, ComfyUI integration, and fast decoders like FlashVDM. Lightweight alternatives like Hunyuan3D-2mini require around 5 GB VRAM. When polygon flow matters for games, it flags that open meshes produce dense triangle soup, pointing to hosted PolyGen or manual retopology passes.
The open models ship under the Tencent Hunyuan Community License, which excludes the European Union, the United Kingdom, and South Korea. Projects exceeding 1,000,000 monthly active users must request a dedicated commercial license from Tencent.
What it helps with
- choose between self-hosted weights and hosted Hunyuan3D APIs
- size GPU VRAM for local inference or ComfyUI setups
- check commercial license terms and territory exclusions
- select retopology and PBR texture pipelines for 3D meshes
Example prompts for the agent
- Compare Hunyuan3D-2.1 open weights with hosted Hunyuan3D-PolyGen for game assets
- What GPU memory is required to run Hunyuan3D-2mini locally?
- Check the commercial licensing terms for Hunyuan3D in the UK and EU
How to install tencent-hunyuan3d
1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill tencent-hunyuan3d -a claude-code2Manually: put the files in place
~/.claude/skills/tencent-hunyuan3d/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/tencent-hunyuan3d/
1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill tencent-hunyuan3d -a codex2Manually: put the files in place
.agents/skills/tencent-hunyuan3d/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill tencent-hunyuan3d -a cursor2Manually: put the files in place
.cursor/skills/tencent-hunyuan3d/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install calesthio/generative-media-skills skills/providers/3d-generation/tencent-hunyuan3d2Manually: put the files in place
.github/skills/tencent-hunyuan3d/SKILL.md1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill tencent-hunyuan3d -a gemini-cli2Platform CLI
gemini skills install https://github.com/calesthio/generative-media-skills --path skills/providers/3d-generation/tencent-hunyuan3dManually: put the files in place
.devin/skills/tencent-hunyuan3d/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill tencent-hunyuan3d -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about tencent-hunyuan3d
How to install tencent-hunyuan3d in Claude Code?
Run npx skills add calesthio/generative-media-skills --skill tencent-hunyuan3d -a claude-code in your terminal.
What does tencent-hunyuan3d do?
It provides architecture rules, hardware sizing guides, and license compliance checks for Tencent's 3D generative model ecosystem.
What license restrictions apply to Hunyuan3D open weights?
The Tencent Hunyuan Community License excludes use in the EU, the UK, and South Korea. Commercial products with over 1,000,000 MAU require a separate license agreement.
Source text
SKILL.md · MIT
--- name: tencent-hunyuan3d description: >- Generate 3D assets with Tencent's Hunyuan3D family — open-weight self-hosted models (Hunyuan3D-2.0/2.1 and HunyuanWorld / HY-World for scenes) and the hosted, closed API tiers (2.5, PolyGen, 3.0/3.1 via Tencent Cloud and third-party hosts). Use when a task involves image-to-3D or text-to-3D mesh generation, the shape-then-texture (DiT + Paint / PBR) workflow, choosing between self-hosting and a hosted API, checking the Community License's Territory (EU/UK/South Korea) and 1M-MAU commercial gate, sizing GPU/VRAM for local inference, ComfyUI integration, or reviewing and post-processing (retopology, UVs, decimation) the meshes these models produce. Not for image, video, or general LLM tasks. --- # 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: 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 [email protected] 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. --- ## 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: 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. --- ## 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.
© calesthio · MIT · calesthio/generative-media-skills