KawasakiAkasei
acfe5e7ac2
- package hunyuan3dweb/ -> hy3d/ (imports: from hy3d import ...) - CLI: MiniMax-style verb/noun commands (quota/list/status/formats/ download/text/image/multi-view/sketch/animate/texture/topo/cancel/ share/auth/config), global --json/--cookies, env HY3D_COOKIES/HY3D_JSON - exit codes: 0 ok / 1 env / 2 auth-expired / 3 cookie-missing - generation commands support --wait polling with stderr progress - local images auto-upload to COS in image/multi-view/sketch/animate/texture/topo - old commands removed (no backwards compat) - config dir kept at ~/.config/hunyuan3dweb to preserve existing cookies - deps: requests>=2.32.3, browser extras cloakbrowser>=0.3.31/playwright>=1.40 - skill updated: bin/hy3d shim replaces driver.sh; all commands live-verified
4.3 KiB
name, description
| name | description |
|---|---|
| run-hunyuan3dweb | 运行并驱动腾讯混元 3D（hy3d）。当用户要求：跑 hy3d、查混元 3D 配额、列作品、文生 3D / 图生 3D 生成模型、查询生成状态、下载 GLB/OBJ/USDZ 模型，或验证这个项目能否工作时使用。 |
本项目（仓库 gitea.akasei.top/KawasakiAkasei/hy3d）是腾讯混元 3D（https://3d.hunyuan.tencent.com/）的非官方 CLI 与 Python 客户端：签名算法（HMAC-SHA256 密钥派生 Hf6d6KFB3D）、纯 HTTP API + CLI（hy3d）、浏览器登录工具。
驱动入口只有一个：bin/hy3d（免安装 shim，自动设置 PYTHONPATH 并转发到 python3 -m hy3d.cli）。也可 pip install hy3d 后用 PATH 上的 hy3d。下文路径相对仓库根。
前置条件
python3 --version # ≥3.9 ✅ (本机 3.13.12)
python3 -c "import requests" # 缺则: pip install requests
浏览器功能（登录/抓包）另需 playwright、cloakbrowser、chromium、xvfb-run——本机均已装好。
Setup
无安装步骤。仅需登录 cookie：~/.config/hunyuan3dweb/cookies.txt（2026-08-15 曾登录，cookie 可能随时过期，过期用下方 auth 流程处理）。
Run（agent 路径）
bin/hy3d auth status # 登录体检（最先跑这个）
bin/hy3d quota # 配额
bin/hy3d list # 作品列表（2026-08-15 实测 7 个作品）
bin/hy3d formats <creationsId>
bin/hy3d download <creationsId> --format glb -o model.glb
bin/hy3d text "a ceramic teapot" --wait # 文生 3D（消耗 4 配额）轮询到完成
# 更多: status/user/count/image/sketch/animate/texture/topo/cancel/share
退出码（agent 分支判断的依据，已实测）：
| 码 | 含义 | 处理 |
|---|---|---|
| 0 | 成功 | — |
| 1 | 环境/网络/参数/4xx | 看 stderr |
| 2 | 认证失败（token 无效/过期） | hy3d auth login（需人工，见下） |
| 3 | cookie 缺失 | hy3d auth login（需人工，见下） |
典型工作流（2026-08-15 全部实测通过）：auth status → quota → list → 对历史作品 formats/download（下载 512×512 PNG 预览验证过）；text --wait 已验证提交+轮询框架，未在容器内跑完整生成（消耗配额）。
重新登录（退出码 2/3 时唯一出路）
必须由人类用户在真实终端（Claude 的 ! 前缀 stdin 非交互，input() 会 EOF）运行：
python -m hy3d.browser.login # 或安装后: hy3d-login
输邮箱 → 收验证码 → 输验证码，cookie 自动存回 ~/.config/hunyuan3dweb/cookies.txt。登录后浏览器进程自动退出，无残留（2026-08-15 验证）。
Run（人类路径）
pip install -e ".[browser]" # 可选，装好后 hy3d 直接进 PATH
hy3d quota
Test（离线自检）
python3 -m hy3d.sign
# 输出含「派生密钥: Hf6d6KFB3D」即签名算法正确
Gotchas
!前缀跑登录必 EOF ——input()在管道 stdin 上直接EOFError: EOF when reading a line。登录必须真实终端；agent 只能引导用户。- 401 两种码都证明签名正确 ——
"code":"20001"=token 过期（重登）；"code":"999"=cookie 无用户。服务端能分类错误说明请求格式被完全接受。 - 不存在的 creationsId → HTTP 400 空 body（CLI 归为退出码 1），不是 JSON 错误。
- 文生 3D 一次消耗 4 次配额（
count=4固定）；图生 3D 等消耗 1 次。 - 配置目录刻意保持
~/.config/hunyuan3dweb不变——改名后路径改了会丢掉已登录的 cookie。 - 生成类命令（text/image/animate/...）未在容器内完整跑通——验证到提交与轮询框架；正式大规模使用前先
hy3d auth status确认在线，并接受首单可能失败的调试成本。
Troubleshooting
hy3d auth status退出码 2：token 过期。让人在真实终端跑python -m hy3d.browser.login。- 退出码 3：cookie 文件不存在/为空。同上，或检查
HY3D_COOKIES是否指向了错误路径。 EOFError（登录时）：stdin 非交互，换真实终端。401+ 'token无效'：重登，不是代码 bug。python3 -m hy3d.sign的 RuntimeWarning：runpy 与__init__.py重复导入的假警报，无害。