腾讯混元生3D Skill

本版本基于 ClawHub @neck-cn/hy-3d-generation 的本地安装副本改造，发布名为 hy-3d-gen。主要改造点是默认走 TokenHub/OpenAI 兼容 HTTP 接口，并保留腾讯云 SDK 作为显式回退后端。

本地 Codex 安全说明

此安装副本已做安全化处理：脚本不会自动执行 pip install。默认优先使用 TokenHub 的 OpenAI 兼容 HTTP 接口，使用 Python 标准库发起请求，不需要额外依赖；如显式使用 --provider tencent，缺少 tencentcloud-sdk-python 时脚本会退出并提示用户先在明确选择的 Python 环境中手动安装。生成任务会把 prompt、图片 URL 或 Base64 图片数据发送到腾讯混元生3D接口。

本地测试凭证可放在 skill 根目录的 .env 文件中，权限应为 600。脚本只会读取 HY3D_OPENAI_API_KEY、TENCENT_MAAS_API_KEY、TOKENHUB_API_KEY、TENCENTCLOUD_SECRET_ID、TENCENTCLOUD_SECRET_KEY、TENCENTCLOUD_TOKEN，并且不会覆盖进程中已经存在的同名环境变量。

功能描述

本 Skill 提供混元生3D能力，基于腾讯混元大模型，将文本描述或图片智能生成 3D 模型。默认使用 TokenHub OpenAI 兼容协议，可手动回退腾讯云 SDK。支持多视角图片输入、PBR 材质、自定义面数、多种输出格式。

场景	脚本	说明
一站式生成	main.py	提交任务 + 自动轮询，推荐使用
仅提交任务	submit_job.py	仅提交，返回 JobId
仅查询任务	query_job.py	根据 JobId 查询/轮询结果
共享客户端	hy3d_api.py	TokenHub + 腾讯云 SDK 双后端封装，不直接手动运行

🎯 选择规则

用户要求生成3D模型  →  main.py（一站式，最简单推荐）
用户要求提交后自行查询  →  submit_job.py + query_job.py（分步操作）
用户已有 JobId 要查结果  →  query_job.py（单独查询）

如果用户未指定使用哪种模式，Agent 应默认使用 main.py 一站式脚本。

支持特性

• 文生3D：支持文本描述生成 3D 模型（最多 1024 字符）
• 图生3D：支持输入图片 URL 或 Base64 生成 3D 模型
• 多视角图片：支持 left/right/back/top/bottom/left_front/right_front 多视角输入
• PBR 材质：支持开启 PBR 材质生成
• 自定义面数：支持 10000-1500000 面数范围
• 多种生成类型：Normal（带纹理）、LowPoly（智能拓扑）、Geometry（白模）、Sketch（草图生成）
• 多种输出格式：默认 obj+glb，可选 STL、USDZ、FBX
• 模型版本选择：支持 3.0 和 3.1 版本
• OpenAI 兼容接口：优先使用 TokenHub https://tokenhub.tencentmaas.com/v1/api/3d/submit 与 /query
• 双后端选择：--provider auto 默认优先 TokenHub；--provider tokenhub 强制 TokenHub；--provider tencent 强制腾讯云 SDK
• 显式安装依赖：TokenHub 后端无需额外依赖；腾讯云 SDK 后端需要用户在明确选择的 Python 环境中安装所需 SDK
• 智能凭证检测：优先从环境变量获取密钥，未配置时提示用户开通

环境配置指引

密钥配置

本 Skill 默认需要 TokenHub OpenAI 兼容 API key；腾讯云 SDK 后端需要腾讯云 API 密钥。

TokenHub / OpenAI 兼容接口（默认）