Hunyuan 3D API: What Builders Should Know

Three game studios I’ve talked with in the past two months are evaluating the same thing: whether to wire Hunyuan 3D into their asset pipeline. One needed to prototype dozens of weapon variants for a vertical slice. One was building a tool that lets non-3D artists ship product visualizations. One wanted to replace a contracted modeling pipeline costing eight weeks per character. The decision isn’t whether AI 3D generation works — it’s which model, which API surface, and what changes in production.

Dora still. This piece is about what’s confirmed, what’s still unsettled, and what builders should ask before committing.

What Hunyuan 3D means for builders

Tencent’s 3D asset generation system

Tencent Hunyuan 3D is the 3D-asset arm of Tencent’s Hunyuan model family. It generates 3D meshes from text, single images, or multi-view image input. Two access paths are confirmed: the Global web app at 3d.hunyuanglobal.com for direct use, and the Hunyuan 3D Model API via Tencent Cloud for enterprise workflows.

Tencent positions the system for production — games, e-commerce visualization, 3D printing, ad creative, film VFX. That positioning is stated in Tencent’s global launch announcement on November 26, 2025. The open-source side — released on the Tencent-Hunyuan GitHub organization — has crossed 3 million Hugging Face downloads since the first 1.0 release, a clear signal the model line is in real workflows, not just benchmarks.

Model versions: what’s actually out, and what isn’t

The version history matters because the architecture changed between major releases, and open-source numbering runs in parallel with the commercial timeline. The public release line:

Hunyuan3D 1.0 — November 2024. Unified text-to-3D / image-to-3D framework.
Hunyuan3D 2.0 — January 2025. Scaled diffusion for high-resolution textured assets.
Hunyuan3D 2.1 — June 2025. Production-ready PBR pipeline, fully open-sourced.
Hunyuan3D 2.5 — June 2025 technical report. ~10B parameters; geometric resolution to 1024.
Hunyuan 3D 3.0 — September 16, 2025. Introduced the 3D-DiT (Diffusion Transformer) architecture.
Hunyuan 3D 3.1 / Global — November 25–26, 2025. International release with English UI and Tencent Cloud API.

If a “3.5” claim shows up in secondary coverage, treat it as needs verification — the public release line is 3.0/3.1 commercial and 2.x open-source. Confirm against current Tencent docs before writing any version into a spec.

Pro vs Rapid: why edition choice matters

The API exposes two editions: Pro and Rapid. Pro is the high-quality path with advanced controls — multi-view input, GenerateType selection (Normal, LowPoly, Geometry, Sketch), and configurable polygon budgets. Rapid is the speed path with simplified parameters, for high-volume pipelines where uniformity matters more than per-asset detail. The endpoint surface splits accordingly: SubmitHunyuanTo3DProJob and SubmitHunyuanTo3DRapidJob, each with its own query endpoint.

For hero assets, Pro. For batch generation where you’ll clean up downstream, Rapid. Parameter differences and per-edition pricing should be pulled from official docs at request time — both move.

What the Hunyuan 3D API supports

Task submission and async status querying

The API runs async. Submitting to SubmitHunyuanTo3DProJob returns a JobId. Polling QueryHunyuanTo3DProJob returns one of four statuses: WAIT, RUN, FAIL, or DONE. When status is DONE, result file URLs are returned in the ResultFile3Ds field. The minimal submit payload, per the Tencent Cloud API documentation:

POST / HTTP/1.1
Host: hunyuan.intl.tencentcloudapi.com
X-TC-Action: SubmitHunyuanTo3DProJob
{ "Prompt": "cat" }

A successful response returns { "JobId": "...", "RequestId": "..." }. Each account gets 3 concurrent tasks by default — the next submission processes only after one of the current three finishes. For higher concurrency, contact sales.

Any production integration needs a job queue, a polling loop with backoff, and webhook receivers if available in your region. Holding an HTTP connection open for the duration of a 3D call is not the right pattern.

GLB output, optional PBR textures, and configurable polygon count

The default output format is GLB — the binary form of glTF, the Khronos glTF specification for efficient transmission of 3D scenes, published as the ISO/IEC 12113:2022 international standard in 2022. PBR textures toggle via the EnablePBR flag; polygon count is configurable in Pro via FaceCount. GenerateType additionally exposes a Geometry mode (white model, no texture) and a Sketch mode that accepts line-art alongside the prompt.

GLB is the right default for 99% of game-engine and web-3D workflows. If a downstream tool requires OBJ, FBX, or USD, plan a conversion step — the API includes SubmitConvert3DFormatJob, but conversion isn’t edge-case free. UV maps and material slots are where things break in practice.

Tencent Cloud API access for enterprise workflows

For teams already on Tencent Cloud, API access slots into existing IAM, billing, and observability. As of the global launch, Tencent has confirmed more than 150 enterprises on the platform in mainland China — including Unity China, Bambu Lab, and Liblib — a useful read on which buyers are in production today: engines, hardware, creative platforms.

For teams outside the Tencent Cloud ecosystem, integration overhead is real — region selection, SecretId/SecretKey management, and SDK availability all worth checking. Tencent ships SDKs for Python, Java, Go, Node.js, PHP, .NET, and C++.

Image-to-3D production workflows

Game assets and prototype environments

The most consistent use case I’ve seen builders ship: rapid prototyping of props, environment dressing, and concept-to-mesh iteration for vertical slices. A 2D sketch becomes a textured GLB in minutes. Whether the mesh is production-final or “block-out an artist cleans up” depends on the asset class and topology requirements. For animated or skinned characters, plan retopology; for static props, often shippable after a normals/scale pass.### E-commerce product visualization

For e-commerce, the 3D model is rarely the final deliverable — it’s the source for 360° spins, AR try-ons, or alt-angle product images. The pipeline maps cleanly: product photo in, GLB out, downstream rendering or AR delivery handled elsewhere. Pro’s multi-view input is the lever — front, side, and back reference photos meaningfully reduce silhouette ambiguity vs. single-view inference.

3D printing and design review

For 3D printing, watertight geometry matters more than texture quality. Pre-print, the mesh should be checked in a slicer for non-manifold edges, holes, and inverted normals. Most AI-generated meshes pass these checks for simple objects and fail for thin features or intricate cavities. Bambu Lab’s place in the customer list is notable here — a category where the mesh has to survive a physical printer, not just a renderer. Run a test print before assuming print-readiness.

Production readiness checklist

Output format compatibility with Unity, Unreal Engine, and Blender

GLB imports natively into Unity via Unity glTFast — the official Unity package, registered as the default importer for .gltf and .glb — into Unreal Engine via the built-in glTF Importer, and into Blender via its built-in importer.

What breaks: material assignments when PBR maps pack differently than the engine expects, scale (units default differently in different tools), and skeletal data for rigged assets. None are deal-breakers, but each adds a step. For animation-bound assets, Tencent’s SubmitAutoRiggingJob handles a first-pass rig; whether it’s shippable for your animation system is its own evaluation.

Texture quality, topology, and polygon budget

Generated topology is rarely the clean quad layout an artist would hand-build. For static props, this matters less. For deformable or animated assets, it matters a lot. Plan retopology for anything that deforms — Tencent’s Submit3DSmartTopologyJob is one option (triangle/quad, three density levels), but third-party tools often produce cleaner results for hero assets.Polygon budgets — what Pro can produce vs. what your platform can render — should match at the API call level via FaceCount, not in post. Generating 500K polys and decimating to 30K downstream is more expensive and lossy than asking for 30K up front.

Queueing, retries, and failed jobs

Failed jobs return FAIL with ErrorCode and ErrorMessage populated. Check current docs for whether failed jobs are billable and what retry semantics apply. Build retry around documented behavior, not assumption. Idempotency keys, if supported, save you from double-billing on network retries.

Commercial use and license review

For closed-API access via Tencent Cloud, the commercial-use terms are in the service agreement — review with legal before shipping. For open-source releases, each repo’s LICENSE file is the source of truth — they vary by release and update. Regional restrictions (the open-source 2.5 family has noted restrictions in some jurisdictions) are worth checking at integration time, not at planning time.

Direct Tencent API vs aggregation layer

When direct API access is enough

If a product depends on exactly one 3D model and the team is already on Tencent Cloud, direct access is the simpler path. One vendor, one SDK, one billing line. Tencent’s free tier — 200 enterprise credits on registration and 20 free daily generations on the consumer app — is enough to evaluate without paid spend.

When multi-model access reduces switching risk

If the product needs to compare 3D models across providers — Hunyuan 3D, Trellis, TripoSR, and others on Hugging Face — or if model selection is likely to change as the field evolves (it is), an aggregation layer reduces switching cost. A unified interface means model changes become a parameter swap, not an integration rewrite.

Aggregation layers aren’t free — they add a hop, and per-provider quirks have to live somewhere. WaveSpeedAI’s API documentation describes one pattern for unified access. The trade-off is consistent: a thin layer between your code and providers, in exchange for not maintaining each provider’s quirks. Worth evaluating against direct access on your specific workload, not in the abstract.

FAQ

Does Hunyuan 3D output GLB or other 3D formats?

GLB is the documented default. OBJ has been confirmed in third-party coverage, and the API includes SubmitConvert3DFormatJob for pipelines requiring FBX or USD. For most game-engine and web pipelines, GLB is what you want. What is the difference between Hunyuan 3D Pro and Rapid? Pro is the high-quality edition with advanced controls — multi-view input, four GenerateType modes (Normal, LowPoly, Geometry, Sketch), configurable polygon budgets, optional PBR. Rapid is the speed-optimized edition with simplified parameters, for high-volume workflows where uniformity matters more than per-asset detail. Confirm parameter differences and pricing against official docs.

Does the Hunyuan 3D API run synchronously or async?

Async. Submit a job, get a JobId, poll QueryHunyuanTo3DProJob until Status is DONE or FAIL. There’s no “submit and wait for the binary” endpoint — the model takes too long. Each account gets 3 concurrent tasks by default; plan around that from the start.

Is Hunyuan 3D free to use?

Yes, with limits. Per Tencent’s launch announcement, individual creators on the Global web app receive 20 free generations per day, and enterprise API users receive 200 free credits on registration. Beyond that, usage is billed. Verify current specifics against the official pricing page — these change.

When should builders compare Hunyuan 3D with other 3D models?

Before integration, not after. Run a representative workload — five to ten reference inputs covering the categories your product needs — through Hunyuan 3D and at least one alternative. Compare on geometric accuracy, texture quality, topology, generation time, and price per asset. The right comparison takes an afternoon and saves a migration project later.

Conclusion

Hunyuan 3D is a serious option for builders shipping 3D AI into production. The API surface is documented, the output format is a Khronos / ISO international standard, and the customer list — Unity China, Bambu Lab, Liblib, and 150+ more — shows validation across engines, hardware, and creative tools. What’s still moving — version capabilities, edition parameters, pricing tiers — needs verifying against official docs at integration time, not from secondary coverage.

The teams I’ve watched get this right treated 3D model selection as its own architectural decision, with its own evaluation criteria and observability. Run a real workload through. That’ll tell you more than anything I say.

Previous posts: