前言¶
做 3D 內容時，常見路徑是建模軟件手工搭 mesh，或自己對接雲 API、寫輪詢與下載邏輯。文本、單圖、多視角圖要變成可用的 glb/obj，還要處理任務狀態、輸出格式和麪數等參數，集成成本高。下面介紹 SkillHub 上的 HY 3D Generation（@tencent-adm/hy-3d-generation）：把騰訊雲混元生 3D 3.0、3.1 能力封裝成 Agent 可執行的腳本與規範，在對話裏用自然語言觸發文生 3D、圖生 3D 等流程。
這是什麼¶
HY 3D Generation 是騰訊雲智能創作團隊發佈的企業來源 Skill（design-media 分類，當前版本 1.0.0）。它基於騰訊混元大模型，將文字或圖片生成更高精度、更高質量的 3D 模型；Skill 內提供 main.py、submit_job.py、query_job.py，對接 tencentcloud.ai3d.v20250513 的 SubmitHunyuanTo3DProJob / QueryHunyuanTo3DProJob（Endpoint：ai3d.tencentcloudapi.com）。
SkillHub 頁面標註 requires_api_key=true：使用前需在騰訊雲開通混元 3D 服務並配置 API 密鑰。
核心功能¶
以下能力與 Skill 簡介及 SKILL.md 一致，可按生成方式選用參數：
| 能力 | 說明 |
|---|---|
| 文生 3D | --prompt，中文推薦，最多 1024 字符 |
| 圖生 3D | --image-url 或 --image-base64 |
| 多視圖生 3D | --multi-view JSON，視角含 left/right/back/top/bottom/left_front/right_front |
| 單幾何（白模） | --generate-type Geometry |
| 草圖生 3D | --generate-type Sketch，可配合圖片與 prompt |
| 智能拓撲 | --generate-type LowPoly，可選 --polygon-type triangle/quadrilateral |
其他已文檔化的選項包括：模型版本 3.0 / 3.1（3.1 不支持 LowPoly）、PBR（--enable-pbr）、面數 10000–1500000（--face-count）、輸出格式 STL / USDZ / FBX（默認 obj+glb）。
腳本分工：
main.py：提交任務並自動輪詢，默認推薦。submit_job.py：只提交，返回 JobId。query_job.py：按 JobId 查詢或輪詢結果。
安裝與啓用¶
1. 安裝 SkillHub CLI¶
若本機尚未安裝，可先檢查版本：
command -v skillhub && skillhub --version
未安裝時，按 SkillHub 安裝說明 執行（僅 CLI）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
2. 安裝本 Skill¶
安裝時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 可能無法被識別。官方頁面給出的安裝方式爲：參考 https://skillhub.cn/install/skillhub.md，安裝 @tencent-adm/hy-3d-generation。
CLI 搜索索引中的安裝命令爲：
skillhub install hy-3d-generation --namespace tencent-adm --dir <skills 目錄>
常見客戶端 skills 路徑（來自 SkillHub 安裝文檔）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/
安裝完成後，將 Skill 目錄記爲 <SKILL_DIR>（例如 ~/.cursor/skills/@tencent-adm/hy-3d-generation），下文命令中的腳本路徑均相對於該目錄下的 scripts/。
3. 配置騰訊雲密鑰¶
- 在 騰訊雲 3D 視覺創作控制台 開通混元 3D 服務。
- 在 API 密鑰管理 獲取 SecretId、SecretKey。
- 設置環境變量（Linux / macOS 示例）：
export TENCENTCLOUD_SECRET_ID="你的SecretId"
export TENCENTCLOUD_SECRET_KEY="你的SecretKey"
Skill 依賴 Python 3.7+ 與 tencentcloud-sdk-python；首次運行腳本時會嘗試自動安裝 SDK，也可手動執行 pip install tencentcloud-sdk-python。
典型用法¶
默認走一站式腳本。將 <SKILL_DIR> 替換爲實際安裝路徑。
文生 3D（基礎）：
python3 <SKILL_DIR>/scripts/main.py --prompt "一隻可愛的卡通貓咪"
圖生 3D：
python3 <SKILL_DIR>/scripts/main.py --image-url "https://example.com/cat.jpg"
3.1 版本 + PBR：
python3 <SKILL_DIR>/scripts/main.py --prompt "一個精緻的茶壺" --model 3.1 --enable-pbr
白模（Geometry）：
python3 <SKILL_DIR>/scripts/main.py --prompt "一個機器人" --generate-type Geometry
僅提交、稍後查詢：
python3 <SKILL_DIR>/scripts/main.py --prompt "一座城堡" --no-poll
python3 <SKILL_DIR>/scripts/query_job.py "job-xxxxxxxxxxxx"
成功時 JSON 中會包含 result_files（含 glb、obj 等類型的下載 URL 與預覽圖）。文檔說明：生成文件 URL 有效期爲 24 小時，任務通常需 1～5 分鐘；Agent 側規範要求直接執行腳本並回傳真實 URL，不得在 API 失敗時編造結果。
適用場景與注意¶
適合誰：需要在 Cursor、Claude Code、Codex 等 Agent 環境中做 3D 原型、資產生成、多模態試樣的開發者或設計相關崗位；已具備或可申請騰訊雲混元 3D 賬號的團隊。
使用注意：
- 必須配置
TENCENTCLOUD_SECRET_ID/TENCENTCLOUD_SECRET_KEY，勿將密鑰寫入代碼倉庫。 - 圖生輸入：URL 圖分辨率 128～5000，大小 ≤ 8MB；Base64 ≤ 6MB。
- 模型 3.1 與 LowPoly 不能同時使用（參數表中的限制）。
- 分步場景用
submit_job.py+query_job.py；已有 JobId 時單獨用query_job.py。
SkillHub 統計（以頁面抓取爲準）：評分 100000，下載 6337，安裝 198。
結尾¶
HY 3D Generation 把混元生 3D 的提交、輪詢、格式與生成類型收斂到一套 Skill 腳本與 Agent 執行規範，減少自建對接成本。官方入口：SkillHub 技能頁、API 座標頁。
