hunyuan-3d-material
Generate textures with HY-3D-Texture or unwrap UVs with HY-3D-UV through Tencent TokenHub. Use for existing model texturing, PBR, preserving UVs, automatic UV unwrapping, task queries, and model/mater
SKILL.mdskills/hunyuan-3d-material/SKILL.md
GitHub混元 3D 材质
接入 HY-3D-Texture 纹理贴图生成和 HY-3D-UV 自动 UV 展开。模型生成使用 hunyuan-3d-generator,拆分/减面/格式转换使用 hunyuan-3d-mesh;烘焙和动画尚未接入本技能。
操作选择
- 生成纹理:
texture,模型texture,输入单几何 OBJ/GLB 和文字或参考图。图片限制、多视图 schema 和版本说明见 references/texture.md。 - 展开 UV:
uv(别名unwrap),模型uv,输入 FBX/OBJ/GLB,不传文字、图片或纹理参数。请求使用file.url,可选--file-type,与纹理的file_3d.url不同。 - UV 文档标注输入 60M、3 万面、最多 100 个组件/连通域。提交前核对已知大小和几何统计,可用
--input-size-bytes、--face-count、--component-count做本地预检;这些是输入测量值,不是输出目标,也不发送给 API。单位和面数口径及超限处理见 references/uv.md。 - 展开 UV 后再贴图时,先检查 UV 结果,选择其中的 OBJ/GLB 链接作为纹理输入,按需启用
--enable-keep-uv。这是两次独立任务,按用户授权范围执行;UV 操作自身不自动减面或生成纹理。
纹理输入
- 模型为可访问的 HTTPS OBJ/GLB 链接,请求字段为
file_3d.url。纹理接口不接受 FBX/ZIP。两类操作都不直接提交本地模型路径;需要时先准备相应格式的副本,再使用用户指定或已授权的存储链接,不自动上传到第三方。 - 文字与主参考图必选其一,不能同时传。文字最多 200 字符,优先中文正向材质描述;本地参考图支持 JPEG/PNG,使用请求体
image.base64,远端图使用image.url。不要发送专业版的顶层image_base64/image_url。 --enable-pbr请求 PBR 材质;--enable-keep-uv请求保留已有 UV。两者默认关闭。用户需要保留既有 UV 时先确认模型具备所需 UV;保留 UV 与 UV 展开是不同任务。--texture-size接受 720~4096 的整数,表示正方形贴图边长,未指定使用服务端默认 4096;不额外限制为 2 的幂。- 多视图使用
--view VIEW=FILE_OR_HTTPS_URL;每个视角只传一张。纹理接口的视图字段是view/image,与生成接口不同。使用前阅读 references/texture.md,其中记录了版本说明缺口及与主参考图不同的尺寸/容量限制。
执行与恢复
- 使用 Python 3.10+。依赖相邻安装的最新版
hunyuan-3d-generator,共用客户端须支持纹理图片脱敏;运行时不需要第三方库。解析脚本、输入和输出为绝对路径。 - 凭据优先读取进程环境变量
TOKENHUB_API_KEY,兼容HUNYUAN_3D_API_KEY/TENCENT_HUNYUAN_API_KEY。真实密钥不进入脚本、命令行参数或日志;仅支持 TokenHub,不混用旧 AI3D 密钥或任务。 - 检查输入,再用
--dry-run校验。预检不联网,只检查参数、本地参考图和提供的测量值,不能据此证明远端模型大小、面数、组件数量、UV 或图片内容符合要求。未知的统计值不填零或猜测值。 - 用户已授权相应操作且输入充分时提交一次;仅要求接入 API 或完善技能时不提交付费任务。
texture/uv提交、等待并下载;submit只提交,默认纹理,UV 须传--model uv。收到 ID 后报告任务 ID、模型和地域。 - 默认并发 1,轮询至少间隔 5 秒。中断/超时/下载失败后用原 ID、模型和地域查询。
query兼容既有纹理流程,默认仍为texture;UV 任务必须传--model uv。提交结果不确定或没有 ID 时先检查服务端记录,不自动重提,也不因参数拒绝换模型重做。 - 任务 ID 有效期 24 小时,完成后及时下载
data中全部模型、图片、纹理及 MTL 资源,保留原有资源关系。返回文件绝对路径,并区分云端完成、下载完成和材质检查完成。 - 需要质量检查时在 Blender 导入副本:UV 结果检查 UV 层、重叠、拉伸和几何变化,纹理结果核对绑定、接缝和 PBR 通道。预览图不能替代模型检查;未检查就不保证 UV 质量、贴图完整或游戏就绪。
命令
以下从技能目录展示命令结构;实际运行使用已解析的绝对路径,example.com 是占位链接。
python scripts/hunyuan_material.py texture --file-url "https://example.com/model.glb" --prompt "青绿色釉面陶瓷,细腻裂纹" --enable-pbr --texture-size 2048 --dry-run
python scripts/hunyuan_material.py texture --file-url "https://example.com/model.glb" --prompt "青绿色釉面陶瓷,细腻裂纹" --enable-pbr --texture-size 2048 --output-dir textures
python scripts/hunyuan_material.py texture --file-url "https://example.com/model.obj" --image reference.png --enable-keep-uv --output-dir textures
python scripts/hunyuan_material.py submit --file-url "https://example.com/model.glb" --image-url "https://example.com/reference.png"
python scripts/hunyuan_material.py query JOB_ID --wait --download --output-dir textures
python scripts/hunyuan_material.py uv --file-url "https://example.com/model.fbx" --face-count 30000 --component-count 20 --dry-run
python scripts/hunyuan_material.py uv --file-url "https://example.com/model.glb" --output-dir uv-output
python scripts/hunyuan_material.py submit --model uv --file-url "https://example.com/model.obj"
python scripts/hunyuan_material.py query UV_JOB_ID --model uv --wait --download --output-dir uv-output
python scripts/hunyuan_material.py check-auth
模型可写短名 texture / uv 或完整名 hy-3d-texture / hy-3d-uv,须与操作及原任务一致。--base-url 采用共用客户端的 TokenHub 官方地域白名单,默认广州;check-auth 只读取模型目录,不证明特定模型权限或额度充足。
维护
- 图片限制、视图 schema 和服务端差异:references/texture.md。
- UV 输入限制、测量值和服务端字段:references/uv.md。
- 从本技能目录运行
python -B -m unittest discover -s scripts -p 'test_*.py' -v,测试模拟网络并阻止真实连接。 - 修改共用客户端时同时运行生成与网格技能回归测试;用 skill-creator 的
quick_validate.py检查结构。