KawasakiAkasei
956b015ee0
- driver.sh: PYTHONPATH-based, no-install CLI wrapper with auth diagnostics - exit codes: 0 ok / 1 env / 2 auth-expired / 3 cookie missing - verified live 2026-08-15: quota, list, status, formats, download - text (quota-consuming) documented as request-layer verified only
5.5 KiB
name, description
| name | description |
|---|---|
| run-hunyuan3dweb | 运行并驱动腾讯混元 3D Python 客户端。当用户要求：跑 hunyuan3dweb、查混元 3D 配额、列作品、文生 3D / 图生 3D 生成模型、查询生成状态、下载 GLB/OBJ/USDZ 模型，或验证这个项目能否工作时使用。 |
本项目是腾讯混元 3D（https://3d.hunyuan.tencent.com/）的非官方 Python 客户端：签名算法（HMAC-SHA256 + 密钥派生）、纯 HTTP API 调用、浏览器登录工具。无需 pip install——通过 PYTHONPATH 从源码直接运行。
唯一驱动入口：.claude/skills/run-hunyuan3dweb/driver.sh（下文所有路径相对仓库根 /opt/hunyuan3dweb）。
前置条件
python3 --version # ≥3.8 ✅ (本机 3.13.12)
python3 -c "import requests" # 缺则: pip install requests
浏览器功能（登录/抓包）另需 playwright、cloakbrowser、chromium、xvfb-run——本机均已装好。
Setup
无安装步骤。依赖的两个东西：
- 仓库路径：driver 已内置（
PYTHONPATH自动指向仓库根）。 - 登录 cookie：
~/.config/hunyuan3dweb/cookies.txt（已存在，2026-08-15 登录过，当前有效）。过期后用下面"重新登录"一节处理。
Run（agent 路径）——driver.sh
.claude/skills/run-hunyuan3dweb/driver.sh verify # 三重自检（最快确认能用）
| 命令 | 作用 |
|---|---|
driver.sh verify |
环境 + 离线签名 + 在线配额 三重自检 |
driver.sh quota |
查配额，输出 remainQuota/totalQuota |
driver.sh list |
作品列表（JSON，含 totalCount/creations） |
driver.sh status <creationsId> |
生成状态（json/轮询用 state 字段） |
driver.sh text "<prompt>" |
文生 3D 提交（消耗配额，出 4 个） |
driver.sh formats <creationsId> |
可用下载格式（glb/obj/fbx/stl/usdz/mp4/gif…） |
driver.sh download <creationsId> [--format glb] [--output PATH] |
下载模型到当前目录 |
其余 API（图生 3D、多视角、动画、贴图、减面）直接 import 客户端调用
（api_complete.py 的 Hunyuan3DAPIComplete），10+ 种生成模式同签名同会话。
本容器内已实测：quota/list/status/formats/download（2026-08-15，7 个作品齐全）；
text 只验证到请求构造层（消耗配额，未实测全流程）。
退出码：0 成功 · 1 环境/其他 · 2 认证失败（需重新登录）· 3 cookie 缺失。
收到 2/3 时按下面"重新登录"处理，不要把栈当 bug 报告。
典型工作流（文生 3D + 轮询）：
.claude/skills/run-hunyuan3dweb/driver.sh quota # 先看余额
.claude/skills/run-hunyuan3dweb/driver.sh text "a ceramic teapot" # → creationsId
.claude/skills/run-hunyuan3dweb/driver.sh status <creationsId> # 轮询到 state=success
.claude/skills/run-hunyuan3dweb/driver.sh download <creationsId> --format glb
重新登录（认证失败时唯一出路）
收到退出码 2（"code":"20001" token 无效 / "999" cookie 无用户）时：
必须由人类用户在真实终端（不是 Claude 的 ! 前缀——stdin 非交互，input() 会 EOF）运行：
PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.browser.login
按提示输邮箱 → 收验证码 → 输验证码，登录态自动存回 cookies.txt。
登录完成后浏览器进程自动退出，无资源残留（2026-08-15 验证：登录后零残留进程）。
Run（人类路径）
PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.cli quota # 等价 CLI
PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.cli list
PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.cli text "a red apple"
Test（离线自检）
PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.sign
# 派生密钥: Hf6d6KFB3D ← 输出里有这行即签名算法正确
Gotchas
!前缀跑登录必 EOF ——input()在管道 stdin 打开即 EOF（EOFError: EOF when reading a line）。登录必须真实终端；agent 只能引导用户去跑。- 401 有两种，别混 ——
"code":"20001"=token 过期（重登）；"code":"999"=cookie 无用户（重登或检查 cookie 文件）。两者都证明签名本身是对的（服务端能分类错误）。 - 不存在的 creationsId → HTTP 400 空 body，不是 JSON 错误（2026-08-15 实测）。
python3 -m hunyuan3dweb.sign有 RuntimeWarning（'hunyuan3dweb.sign' found in sys.modules...）——runpy 与__init__.py重复导入的假警报，无害，输出仍正确。- 文生 3D 固定出 4 个模型（
count=4），一次消耗 4 次配额；generate_from_text的count参数会覆盖 UI 行为。 download输出到 CWD——某次下载 86KB 预览图实测 2–3 秒；GLB 可能几十 MB，注意磁盘和时间。正式大规模跑之前先quota确认登录态在线。
Troubleshooting
driver.sh verify打印 AUTH_EXPIRED / 退出码 2：token 过期。让人在真实终端跑PYTHONPATH=/opt/hunyuan3dweb python3 -m hunyuan3dweb.browser.login，成功后再 verify。EOFError: EOF when reading a line（登录时）：stdin 非交互。换真实终端，不要用!。requests.exceptions.HTTPError: 401+ 中文消息 'token无效'：同上，重登。不是代码 bug，别改代码。- cookie 想换账号：
HUNYUAN3D_COOKIES=/path/to/other/cookies.txt driver.sh quota。 - driver 里 python 找不到模块：确认
PYTHONPATH含仓库根（driver 会自动设置）。