前言¶
做 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 坐标页。
