HY 3D Generation

Problem to solve

When you have a text description, one product image, or multiple view images but need a downloadable 3D model, manual modeling can be costly, and calling a 3D generation service directly avoids re-implementing cloud API submission, polling, error handling, and result parsing.

How the skill works

The skill wraps two Tencent Cloud ai3d operations: SubmitHunyuanTo3DProJob and QueryHunyuanTo3DProJob. By default it uses main.py, accepting --prompt, --image-url, --image-base64, or --multi-view, then submits the job and polls until completion.

It supports PBR materials, face counts from 10000 to 1500000, generation types such as Normal, LowPoly, Geometry, and Sketch, and output formats including obj+glb, STL, USDZ, and FBX. For asynchronous workflows, submit_job.py can return a JobId first, and query_job.py can check status later.

The result usually includes file type, Url, and PreviewImageUrl; 3D file URLs expire after 24 hours.

Boundaries and cautions

• It requires an enabled Hunyuan 3D service and Tencent Cloud API credentials, preferably read from environment variables.
• Generation usually takes 1 to 5 minutes, and result URLs should be saved promptly because they expire.
• Model 3.1 does not support LowPoly; image resolution should be 128~5000, with URL input under 8MB and Base64 input under 6MB.
• On failure, keep ErrorCode and ErrorMessage visible instead of inventing file URLs.