hy3d/skill/run-hy3d/SKILL.md

name, description

name	description
run-hy3d	运行并驱动腾讯混元 3D（hy3d）。当用户要求：跑 hy3d、查混元 3D 配额、列作品、文生 3D / 图生 3D 生成模型、查询生成状态、下载 GLB/OBJ/USDZ 模型，或验证 hy3d 能否工作时使用。

hy3d 是腾讯混元 3D（https://3d.hunyuan.tencent.com/）的非官方 CLI 与 Python 客户端，通过 pipx install hy3d（或 pip install hy3d）全局安装，独立于任何仓库工作。命令入口即 PATH 上的 hy3d（源码仓库 bin/hy3d shim 是免安装备选，一般不需要）。

前置条件

hy3d auth status     # 先跑这个——验证安装与登录状态
# 退出码 0 + "登录有效 ✓" 即一切就绪

若命令不存在（未发布 PyPI，需从仓库安装）：

pipx install "git+https://gitea.akasei.top/KawasakiAkasei/hy3d.git"
# 或克隆后 pipx install ".[browser]"；纯源码运行见 README 安装节

Setup

无安装步骤。唯一需要的文件：登录 cookie ~/.config/hy3d/cookies.txt（2026-08-15 曾登录，可能随时过期，过期按下方"重新登录"处理）。

Run（agent 路径）

hy3d auth status          # 登录体检（最先跑）
hy3d quota                # 配额（2026-08-15 实测 20/20）
hy3d list                 # 作品列表（实测 7 个作品）
hy3d formats <creationsId>
hy3d download <creationsId> --format glb -o model.glb
hy3d text "a ceramic teapot" --wait    # 文生 3D（消耗 4 配额）轮询到完成
# 更多: status/user/count/image/sketch/animate/texture/topo/cancel/share
#       全部支持 --json；生成命令支持 --wait/--style/--title

退出码（agent 分支判断依据，已实测）：

码	含义	处理
0	成功	—
1	环境/网络/参数/4xx	看 stderr
2	认证失败（token 无效/过期）	重新登录（需人工，见下）
3	cookie 缺失	重新登录（需人工，见下）

实测记录（2026-08-15）：auth status/quota/list/count/user/formats/download（下载预览图验证过）全部通过；text --wait 已验证提交+轮询框架，未跑完整生成（消耗配额）。

重新登录（退出码 2/3 时唯一出路）

必须由人类用户在真实终端（Claude 的 ! 前缀 stdin 非交互，input() 会 EOF）运行：

hy3d-login               # 邮箱验证码登录（browser 扩展）

输邮箱 → 收验证码 → 输验证码，cookie 自动存回 ~/.config/hy3d/cookies.txt。登录后浏览器进程自动退出，无残留（2026-08-15 验证）。

Python API（同一安装）

from hy3d import Hunyuan3DAPIComplete, upload_image
api = Hunyuan3DAPIComplete()
print(api.get_quota_info())

Test（离线自检）

python -m hy3d.sign   # 在 pipx venv 内（~/.local/share/pipx/venvs/hy3d/bin/python3）
# 输出含「派生密钥: Hf6d6KFB3D」即签名算法正确

---

Gotchas

• ! 前缀跑登录必 EOF —— input() 在管道 stdin 上直接 EOFError。登录必须真实终端；agent 只能引导用户。
• 401 两种码都证明签名正确 —— "code":"20001"=token 过期（重登）；"code":"999"=cookie 无用户。
• 不存在的 creationsId → HTTP 400 空 body（CLI 归为退出码 1），不是 JSON 错误。
• 文生 3D 一次消耗 4 次配额（count=4 固定）；图生 3D 等消耗 1 次。
• 配置目录 ~/.config/hy3d 独立于仓库——卸载重装/删仓库不影响登录态。
• generation 类命令（text/image/animate/...）未完整跑通过——验证到提交与轮询框架；大规模使用前先 hy3d auth status。

Troubleshooting

• hy3d auth status 退出码 2：token 过期。让人在真实终端跑 hy3d-login。
• 退出码 3：cookie 缺失。同上，或检查 HY3D_COOKIES 是否指向错误路径。
• command not found: hy3d：pipx install "git+https://gitea.akasei.top/KawasakiAkasei/hy3d.git"（browser 扩展可选，见 README）。
• EOFError（登录时）：stdin 非交互，换真实终端。
• 401 + 'token无效'：重登，不是代码 bug。