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
87 lines
4.3 KiB
Markdown
87 lines
4.3 KiB
Markdown
---
|
||
name: run-hunyuan3dweb
|
||
description: 运行并驱动腾讯混元 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`。下文路径相对仓库根。
|
||
|
||
## 前置条件
|
||
|
||
```bash
|
||
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 路径）
|
||
|
||
```bash
|
||
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）运行：
|
||
|
||
```bash
|
||
python -m hy3d.browser.login # 或安装后: hy3d-login
|
||
```
|
||
|
||
输邮箱 → 收验证码 → 输验证码，cookie 自动存回 `~/.config/hunyuan3dweb/cookies.txt`。登录后浏览器进程自动退出，无残留（2026-08-15 验证）。
|
||
|
||
## Run（人类路径）
|
||
|
||
```bash
|
||
pip install -e ".[browser]" # 可选，装好后 hy3d 直接进 PATH
|
||
hy3d quota
|
||
```
|
||
|
||
## Test（离线自检）
|
||
|
||
```bash
|
||
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` 重复导入的假警报，无害。 |