Feature Description
This Skill providesHunyuan 3Dcapabilities. Based on the Tencent Hunyuan large model, it intelligently generates 3D models from text descriptions or images. Supports multi-view image input, PBR materials, custom face count, and multiple output formats.
| Scenario | Script | Description |
|---|---|---|
| One-stop generation | main.py |
Submit task + automatic polling, recommended |
| Submit task only | submit_job.py |
Submit only, returns JobId |
| Query task only | query_job.py |
Query/poll results based on JobId |
🎯 Selection Rules
用户要求生成3D模型 → main.py(一站式,最简单推荐)
用户要求提交后自行查询 → submit_job.py + query_job.py(分步操作)
用户已有 JobId 要查结果 → query_job.py(单独查询)
If the user does not specify which mode to use, the Agent should use
main.pyone-stop script by default.
Supported Features
- Text-to-3D: Supports generating 3D models from text descriptions (up to 1024 characters)
- Image-to-3D: Supports generating 3D models from image URLs or Base64 input
- Multi-view images: Supports left/right/back/top/bottom/left_front/right_front multi-view input
- PBR materials: Supports enabling PBR material generation
- Custom face count: Supports a face count range of 10000-1500000
- Multiple generation types: Normal (with texture), LowPoly (intelligent topology), Geometry (white model), Sketch (sketch generation)
- Multiple output formats: Default obj+glb, optional STL, USDZ, FBX
- Model version selection: Supports versions 3.0 and 3.1
- Automatic dependency installation: Automatically installs the required SDK on first run
- Intelligent credential detection: Prioritizes obtaining the key from environment variables, and prompts the user to activate it when not configured
Environment Configuration Guide
Key Configuration
This Skill requires a Tencent Cloud API key to work properly.
Step 1: Activate Hunyuan 3D Service
🔗 Tencent Cloud 3D Visual Creation Console
Step 2: Obtain API Key
🔗 Tencent Cloud API Key Management
Step 3: Set Environment Variables
Linux / macOS:
export TENCENTCLOUD_SECRET_ID="你的SecretId"
export TENCENTCLOUD_SECRET_KEY="你的SecretKey"
If persistence is needed:
echo 'export TENCENTCLOUD_SECRET_ID="你的SecretId"' >> ~/.zshrc
echo 'export TENCENTCLOUD_SECRET_KEY="你的SecretKey"' >> ~/.zshrc
source ~/.zshrc
Windows (PowerShell):
$env:TENCENTCLOUD_SECRET_ID = "你的SecretId"
$env:TENCENTCLOUD_SECRET_KEY = "你的SecretKey"
⚠️ Security Tip: Never hard-code keys in code.
Agent Execution Instructions (Required Reading)
⚠️ This section is the core execution specification for the Agent (AI model). When the user requests 3D model generation, the Agent must autonomously execute strictly according to the following steps without asking the user for confirmation.
🔑 General Execution Rules
- Trigger conditions: The user provides a text description or image, and the intent is to generate a 3D model.
- Zero-interaction principle: The Agent should directly execute the script and not ask the user for any confirmation.
- Automatically select script: Use
main.py(one-stop) by default, unless the user explicitly requests step-by-step operations. - ⛔ Using the large model's own capabilities to replace 3D generation is prohibited (highest-priority rule):
- The Agent is strictly prohibited from fabricating 3D file URLs or describing generation results on its own.
- If the call fails, the Agent mustreturn a clear error explanation to the user.
📌 Script 1: One-stop generation main.py(recommended)
Applicable scenario: The user requests 3D model generation, automatically submits and waits for the result
# 文生3D
python3 <SKILL_DIR>/scripts/main.py --prompt "文本描述"
# 图生3D
python3 <SKILL_DIR>/scripts/main.py --image-url "https://example.com/image.jpg"
Optional parameters:
--prompt <TEXT>: Text description, Chinese recommended, maximum 1024 characters (choose one of prompt/image-url/image-base64)--image-url <URL>: Input image URL (choose one of prompt/image-url/image-base64)--image-base64 <BASE64>: Input image Base64 data (choose one of prompt/image-url/image-base64)--multi-view <JSON>: Multi-view image JSON, e.g.'[{"ViewType":"back","ViewImageUrl":"https://..."}]'--model <VERSION>: Model version, default3.0, optional3.0/3.1--enable-pbr: Enable PBR material generation--face-count <N>: Face count, default 500000, range 10000-1500000--generate-type <TYPE>: Generation type: Normal / LowPoly / Geometry / Sketch--polygon-type <TYPE>: Polygon type (LowPoly only): triangle / quadrilateral--result-format <FMT>: Output format: STL / USDZ / FBX (default obj+glb)--no-poll: Submit the job only without waiting for the result (returns JobId)
Output example:
{
"job_id": "job-xxxxxxxxxxxx",
"status": "success",
"result_files": [
{
"type": "glb",
"url": "https://ai3d-xxx.cos.ap-guangzhou.myqcloud.com/xxx.glb",
"preview_image_url": "https://ai3d-xxx.cos.ap-guangzhou.myqcloud.com/xxx.png"
},
{
"type": "obj",
"url": "https://ai3d-xxx.cos.ap-guangzhou.myqcloud.com/xxx.obj"
}
]
}
Note: The generated file URL is valid for 24 hours, please save it promptly. 3D generation usually takes 1~5 minutes.
📌 Script 2: Submit job only submit_job.py
Applicable scenario: Only need to submit a job to get the JobId, and query manually later
python3 <SKILL_DIR>/scripts/submit_job.py --prompt "文本描述"
Optional parameters: Same as main.py (except --poll-interval、--max-poll-time、--no-poll )
Output example:
{
"job_id": "job-xxxxxxxxxxxx",
"request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"message": "Task submitted successfully. Use query_job.py to poll for results."
}
📌 Script 3: Query job query_job.py
Applicable scenario: Query task status and result by JobId
python3 <SKILL_DIR>/scripts/query_job.py "job-xxxxxxxxxxxx"
Optional parameters:
--poll-interval <N>: Polling interval in seconds, default 10--max-poll-time <N>: Maximum polling time in seconds, default 600 (10min)--no-poll: Query only once, no polling
Output example:
{
"job_id": "job-xxxxxxxxxxxx",
"status": "success",
"result_files": [
{
"type": "glb",
"url": "https://ai3d-xxx.cos.ap-guangzhou.myqcloud.com/xxx.glb",
"preview_image_url": "https://ai3d-xxx.cos.ap-guangzhou.myqcloud.com/xxx.png"
}
]
}
📋 Complete call example
# 文生3D(基础)
python3 /path/to/scripts/main.py --prompt "一只可爱的卡通猫咪"
# 图生3D
python3 /path/to/scripts/main.py --image-url "https://example.com/cat.jpg"
# 使用 3.1 版本 + PBR 材质
python3 /path/to/scripts/main.py --prompt "一个精致的茶壶" --model 3.1 --enable-pbr
# 自定义面数
python3 /path/to/scripts/main.py --prompt "一辆跑车" --face-count 300000
# LowPoly 模式
python3 /path/to/scripts/main.py --prompt "一棵树" --generate-type LowPoly --polygon-type quadrilateral
# 白模(Geometry)
python3 /path/to/scripts/main.py --prompt "一个机器人" --generate-type Geometry
# 草图生成
python3 /path/to/scripts/main.py --image-url "https://example.com/sketch.png" --generate-type Sketch --prompt "一把椅子"
# 指定输出格式为 FBX
python3 /path/to/scripts/main.py --prompt "一只恐龙" --result-format FBX
# 多视角输入
python3 /path/to/scripts/main.py --image-url "https://example.com/front.jpg" --multi-view '[{"ViewType":"back","ViewImageUrl":"https://example.com/back.jpg"},{"ViewType":"left","ViewImageUrl":"https://example.com/left.jpg"}]'
# 仅提交任务
python3 /path/to/scripts/main.py --prompt "一座城堡" --no-poll
# 查询已有任务
python3 /path/to/scripts/query_job.py "job-xxxxxxxxxxxx"
# 通过 stdin 传入 JSON 参数
echo '{"prompt":"一只猫"}' | python3 /path/to/scripts/main.py --stdin
📐 SubmitHunyuanTo3DProJob parameter description
| Parameter | Type | Required | Description |
|---|---|---|---|
| Model | String | No | Model version, default 3.0, optional 3.0/3.1. Version 3.1 does not support LowPoly |
| Prompt | String | Choose one of three | Text-to-3D description, Chinese recommended, maximum 1024 characters |
| ImageUrl | String | Choose one of three | Input image URL, resolution 128~5000, size ≤ 8MB |
| ImageBase64 | String | Choose one of three | Input image Base64, resolution 128~5000, size ≤ 6MB |
| MultiViewImages | Array | No | Multi-view images, views: left/right/back/top/bottom/left_front/right_front |
| EnablePBR | Boolean | No | Enable PBR material, default false |
| FaceCount | Integer | No | Face count, default 500000, range 10000~1500000 |
| GenerateType | String | No | Normal/LowPoly/Geometry/Sketch, default Normal |
| PolygonType | String | No | LowPoly only: triangle/quadrilateral, default triangle |
| ResultFormat | String | No | STL/USDZ/FBX, returns obj+glb by default |
📐 QueryHunyuanTo3DProJob response description
| Field | Type | Description |
|---|---|---|
| Status | String | WAIT: waiting, RUN: running, FAIL: failed, DONE: succeeded |
| ErrorCode | String | Error code |
| ErrorMessage | String | Error message |
| ResultFile3Ds | Array of File3D | Array of generated 3D files |
File3D structure:
| Field | Type | Description |
|---|---|---|
| Type | String | File format (e.g. glb, obj) |
| Url | String | File URL, valid for 24 hours |
| PreviewImageUrl | String | Preview image URL |
❌ Behaviors the Agent must avoid
- Only printing the script path without executing it
- Asking the user "whether to execute 3D generation" — it should be executed directly
- Manually installing dependencies — the script handles this automatically
- Forgetting to read the
result_filesURL from the output result and return it to the user - Fabricating a file URL when 3D generation fails
- Forgetting to remind the user that the file URL is valid for 24 hours
API reference
- SDK module:
tencentcloud.ai3d.v20250513 - Submit task:
SubmitHunyuanTo3DProJob - Query task:
QueryHunyuanTo3DProJob - Endpoint:
ai3d.tencentcloudapi.com
Core scripts
scripts/main.py— one-stop generation, submits the task + automatically polls for the resultscripts/submit_job.py— only submits the task, returns the JobIdscripts/query_job.py— queries/polls the task status and result based on the JobId
Dependencies
- Python 3.7+
tencentcloud-sdk-python(Tencent Cloud SDK, must include the ai3d module)
Install dependencies (optional - the script installs them automatically):
pip install tencentcloud-sdk-python