hy-3d-gen

Tencent Hunyuan 3D Skill

This version is adapted from the local installation copy of ClawHub @neck-cn/hy-3d-generation and is published under the name hy-3d-gen. The main adaptation is that it defaults to the TokenHub/OpenAI-compatible HTTP interface, while retaining the Tencent Cloud SDK as an explicit fallback backend.

Local Codex Security Notes

This installation copy has been secured: the script will not automatically execute pip install. By default it prioritizes the TokenHub OpenAI-compatible HTTP interface, using the Python standard library to make requests, with no additional dependencies required; if --provider tencentis explicitly used and tencentcloud-sdk-python is missing, the script will exit and prompt the user to manually install it first in a clearly chosen Python environment. Generation tasks will send the prompt, image URL, or Base64 image data to the Tencent Hunyuan 3D interface.

Local test credentials can be placed in the .env file in the skill root directory, and the permissions should be 600. The script will only read HY3D_OPENAI_API_KEY、TENCENT_MAAS_API_KEY、TOKENHUB_API_KEY、TENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY、TENCENTCLOUD_TOKEN, and will not overwrite environment variables of the same name that already exist in the process.

Feature Description

This Skill providesHunyuan 3Dcapabilities, based on the Tencent Hunyuan large model, intelligently generating 3D models from text descriptions or images. By default it uses the TokenHub OpenAI-compatible protocol, and can manually fall back to the Tencent Cloud SDK. Supports multi-view image input, PBR materials, custom face counts, 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
Shared client	`hy3d_api.py`	TokenHub + Tencent Cloud SDK dual-backend wrapper, not to be run manually directly

🎯 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 default to the main.py one-stop script.

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 multi-view input for left/right/back/top/bottom/left_front/right_front
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 (smart 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
OpenAI-compatible interface: Prioritizes TokenHub https://tokenhub.tencentmaas.com/v1/api/3d/submit and /query
Dual-backend selection：--provider auto defaults to prioritizing TokenHub;--provider tokenhub forces TokenHub;--provider tencent forces the Tencent Cloud SDK
Explicit dependency installation: The TokenHub backend requires no additional dependencies; the Tencent Cloud SDK backend requires the user to install the required SDK in an explicitly selected Python environment
Smart credential detection: Prioritize obtaining the key from environment variables; if not configured, prompt the user to activate the service

Environment configuration guide

Key configuration

This Skill requires a TokenHub OpenAI-compatible API key by default; the Tencent Cloud SDK backend requires a Tencent Cloud API key.

TokenHub / OpenAI-compatible interface (default)

export HY3D_OPENAI_API_KEY="你的 TokenHub API key"

You can also use TENCENT_MAAS_API_KEY or TOKENHUB_API_KEY. Do not write the key into the script source code.

Tencent Cloud SDK backend (optional fallback)

Step 1: Activate Hunyuan 3D service

🔗 Tencent Cloud 3D Visual Creation Console

Step 2: Obtain the 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 strictly follow the steps below. Explicit user confirmation is required before installing dependencies, persisting environment variables, uploading sensitive images, or expanding changes to the local environment.

🔑 General execution rules

Trigger conditions: The user provides a text description or image, and the intent is to generate a 3D model.
Controlled execution principle: When dependencies and credentials have already been configured and the user explicitly wants to generate a 3D model, the Agent may directly execute the script; it must not automatically install dependencies or rewrite shell configuration.
Automatic script selection: Use main.py(all-in-one) by default, unless the user explicitly requests step-by-step operation. Default --provider auto, and if a TokenHub key exists, the OpenAI-compatible interface will be used first.
⛔ It is forbidden to use the large model's own capabilities to replace 3D generation (highest-priority rule)：
- The Agent is strictly prohibited from fabricating 3D file URLs or describing generated results on its own.
- If the call fails, the Agent mustreturn a clear error explanation to the user.

📌 Script 1: All-in-one generation `main.py`(recommended)

Applicable scenarios: 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"

# 强制使用 TokenHub OpenAI 兼容接口
python3 <SKILL_DIR>/scripts/main.py --provider tokenhub --model hy-3d-3.0 --prompt "一只小狗"

# 强制使用腾讯云 SDK 回退
python3 <SKILL_DIR>/scripts/main.py --provider tencent --model 3.0 --prompt "一只小狗"

Optional parameters：

--prompt <TEXT>: Text description, Chinese recommended, up to 1024 characters (choose one of image-url/image-base64)
--image-url <URL>: Input image URL (choose one of prompt)
--image-base64 <BASE64>: Input image Base64 data (choose one of prompt)
--multi-view <JSON>: Multi-view image JSON, such as '[{"ViewType":"back","ViewImageUrl":"https://..."}]'
--model <VERSION>: Model version, default hy-3d-3.0, optional 3.0 / 3.1 / hy-3d-3.0 / hy-3d-3.1
--enable-pbr: Enable PBR material generation
--face-count <N>: Number of faces, 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)
--provider <auto|tokenhub|tencent>: Backend selection, default auto
--no-poll: Only submit the task 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 task only `submit_job.py`

Use case: Only need to submit a task to get a 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 task `query_job.py`

Use case: Query task status and results by JobId

python3 <SKILL_DIR>/scripts/query_job.py "job-xxxxxxxxxxxx" --model hy-3d-3.0

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
--provider <auto|tokenhub|tencent>: Backend selection, default auto
--model <VERSION>: TokenHub queries require the same model as at submission, default hy-3d-3.0

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, options 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, default returns obj+glb

📐 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
Automatically installing dependencies or modifying the global environment—if a Tencent Cloud SDK backend is needed, the user must explicitly choose the installation environment
Forgetting to read the result_files URL from the output result and return it to the user
Fabricating a file URL yourself when 3D generation fails
Forgetting to remind the user that the file URL is valid for 24 hours

API reference

TokenHub submit endpoint：https://tokenhub.tencentmaas.com/v1/api/3d/submit
TokenHub query endpoint：https://tokenhub.tencentmaas.com/v1/api/3d/query
TokenHub authentication:Authorization: Bearer <HY3D_OPENAI_API_KEY>
TokenHub model name:hy-3d-3.0 / hy-3d-3.1
Tencent Cloud SDK module:tencentcloud.ai3d.v20250513
Tencent Cloud SDK submit task:SubmitHunyuanTo3DProJob
Tencent Cloud SDK query task:QueryHunyuanTo3DProJob
Tencent Cloud SDK endpoint:ai3d.tencentcloudapi.com

Core scripts

scripts/main.py — one-stop generation, submit task + automatic polling to wait for results
scripts/submit_job.py — submit task only, returns JobId
scripts/query_job.py — query/poll task status and results based on JobId

Dependencies

Python 3.7+
The TokenHub backend requires no third-party Python dependencies
tencentcloud-sdk-python(only --provider tencent is required, and must include the ai3d module)

Install Tencent Cloud SDK dependencies (optional):

pip install tencentcloud-sdk-python

About this skill

Local Codex Security Notes

Feature Description

🎯 Selection Rules

Supported Features

Environment configuration guide

Key configuration

TokenHub / OpenAI-compatible interface (default)

Tencent Cloud SDK backend (optional fallback)

Agent execution instructions (required reading)

🔑 General execution rules

📌 Script 1: All-in-one generation main.py(recommended)

📌 Script 2: Submit task only submit_job.py

📌 Script 3: Query task query_job.py

📋 Complete call example

📐 SubmitHunyuanTo3DProJob parameter description

📐 QueryHunyuanTo3DProJob response description

❌ Behaviors the Agent must avoid

API reference

Core scripts

Dependencies

📌 Script 1: All-in-one generation `main.py`(recommended)

📌 Script 2: Submit task only `submit_job.py`

📌 Script 3: Query task `query_job.py`