SuperAPI AI Directory

hy-3d-generation

General & other

View repository

Updated 10-16 08:48

About this skill

Tencent Cloud Hunyuan 3D Skill

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.py one-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

  1. Trigger conditions: The user provides a text description or image, and the intent is to generate a 3D model.
  2. Zero-interaction principle: The Agent should directly execute the script and not ask the user for any confirmation.
  3. Automatically select script: Use main.py(one-stop) by default, unless the user explicitly requests step-by-step operations.
  4. ⛔ 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, default 3.0, optional 3.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_files URL 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 result
  • scripts/submit_job.py — only submits the task, returns the JobId
  • scripts/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