refactor: rename project to hy3d, full CLI overhaul

- 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
2026-08-15 22:31:50 +08:00
parent 956b015ee0
commit acfe5e7ac2
23 changed files with 842 additions and 862 deletions
@@ -1,304 +1,164 @@
-# hunyuan3dweb
+# hy3d

-腾讯混元3D (https://3d.hunyuan.tencent.com/) 的 Python API 客户端与浏览器自动化工具。
+非官方腾讯混元 3D CLI 与 Python API 客户端（[3d.hunyuan.tencent.com](https://3d.hunyuan.tencent.com/)）。
+
+纯 Python HTTP 调用腾讯混元 3D 的 AI 能力：**文生 3D、图生 3D、多视角、草图、动画、纹理、智能拓扑减面**，以及配额查询、作品管理、模型下载（GLB/OBJ/FBX/STL/USDZ/MP4/GIF）。
+
+> ⚠️ 非官方项目：对混元 3D Web 前端签名算法的逆向实现，与腾讯无关。仅供个人学习与自动化使用。

 ## 安装

 ```bash
-pip install -e .
+pip install hy3d             # 纯 API 客户端
+pip install "hy3d[browser]"  # 额外安装浏览器工具（登录/抓包/浏览器自动化）
 ```

-如需浏览器自动化功能：
+不安装也能用——克隆仓库后直接用源码跑（无需 `pip install`）：

 ```bash
-pip install -e ".[browser]"
+cd hy3d
+PYTHONPATH=$PWD python3 -m hy3d.cli quota
 ```

-## 登录与配置
+## 快速开始

-第一次使用需要先通过浏览器登录，系统会自动保存 Cookie：
+首次使用需要登录一次（**在真实终端运行**，邮箱验证码登录，无头浏览器）：

 ```bash
-hunyuan3dweb-login
+hy3d auth login
+# → 按提示: 输邮箱 → 收验证码 → 输验证码
+# → cookie 自动保存到 ~/.config/hunyuan3dweb/cookies.txt
 ```

-登录成功后：
- 浏览器 Profile 保存到 `~/.config/hunyuan3dweb/profile`
- Cookie 自动提取到 `~/.config/hunyuan3dweb/cookies.txt`
-
-之后写 Python 脚本无需再处理 Cookie，库会自动读取。
-
-## Python 脚本调用
-
-### 快速开始（自动读取默认 Cookie）
-
-```python
-from hunyuan3dweb import Hunyuan3DAPIComplete
-
-api = Hunyuan3DAPIComplete()
-
-# 查配额
-quota = api.get_quota_info()
-print(f"剩余: {quota['remainQuota']}/{quota['totalQuota']}")
-```
-
-### 1. 文生3D
-
-最简单的模式，无需上传图片。
-
-```python
-from hunyuan3dweb import Hunyuan3DAPIComplete
-
-api = Hunyuan3DAPIComplete()
-
-# 提交生成任务
-result = api.generate_from_text("一只陶瓷花瓶", title="测试")
-cid = result["creationsId"]
-
-# 轮询直到完成（内置轮询，自动打印进度）
-final = api.wait_for_completion(cid)
-print("生成完成")
-```
-
-**完整流水线：文生3D → 提取下载链接**
-
-```python
-from hunyuan3dweb import Hunyuan3DAPIComplete
-
-api = Hunyuan3DAPIComplete()
-
-job = api.generate_from_text(
-    "赛博朋克风格的机械狗",
-    style=api.STYLE_CYBERPUNK
-)
-cid = job["creationsId"]
-
-result = api.wait_for_completion(cid, timeout=600, poll_interval=5)
-
-if result["status"] == "success":
-    models = result.get("result", [])
-    for m in models:
-        if m["status"] == "success":
-            urls = m["urlResult"]
-            print(f"GLB: {urls.get('glb')}")
-            print(f"OBJ: {urls.get('obj')}")
-            print(f"图片: {urls.get('image_url')}")
-```
-
-### 2. 图生3D（本地文件）
-
-本地图片文件可通过浏览器自动化工具上传，也可使用纯 Python 的 COS 上传模块先拿到 `resourceUrl` 再走 API。
+验证登录与配额：

 ```bash
-hunyuan3dweb-generate /path/to/image.png wait
-```
-
-或通过浏览器自动化脚本：
-
-```python
-from hunyuan3dweb.browser.generator import generate_3d
-
-result = generate_3d("/path/to/image.png", wait_for_complete=True)
-print(f"模型地址: {result.get('modelUrl')}")
-```
-
-或通过纯 Python 上传：
-
-```python
-from hunyuan3dweb.cos_upload import upload_image
-from hunyuan3dweb import Hunyuan3DAPIComplete
-
-resource_url = upload_image("/path/to/image.png")
-
-api = Hunyuan3DAPIComplete()
-result = api.generate_from_image(resource_url, title="我的模型")
-```
-
-### 3. 图生3D（API，已有 resourceUrl）
-
-如果你已经有 `resourceUrl`（例如之前通过浏览器上传过），可直接调用 API：
-
-```python
-from hunyuan3dweb import Hunyuan3DAPIComplete
-
-api = Hunyuan3DAPIComplete()
-
-result = api.generate_from_image(
-    image_url="https://3d.hunyuan.tencent.com/api/3d/resource/download?resourceId=...",
-    title="我的模型"
-)
-cid = result["creationsId"]
-
-final = api.wait_for_completion(cid)
-```
-
-### 4. 多图视角生3D（多视图）
-
-使用多张不同角度的图片生成更精确的 3D 模型。
-
-```python
-from hunyuan3dweb import Hunyuan3DAPIComplete
-
-api = Hunyuan3DAPIComplete()
-
-result = api.generate_from_multi_view(
-    image_urls=[
-        "https://.../front.png",
-        "https://.../side.png",
-        "https://.../back.png",
-    ],
-    title="多视图模型"
-)
-cid = result["creationsId"]
-
-final = api.wait_for_completion(cid)
-```
-
-### 5. 草图生3D
-
-```python
-from hunyuan3dweb import Hunyuan3DAPIComplete
-
-api = Hunyuan3DAPIComplete()
-
-result = api.generate_from_sketch(
-    sketch_url="https://...",
-    prompt="一个机器人的草图",
-    title="草图机器人"
-)
-cid = result["creationsId"]
-
-final = api.wait_for_completion(cid)
-```
-
-### 6. 动画生成
-
-需要模型图片 URL 和动作类型。
-
-```python
-from hunyuan3dweb import Hunyuan3DAPIComplete
-
-api = Hunyuan3DAPIComplete()
-
-# 可选动作：MOTION_CAPOEIRA, MOTION_FALLING, MOTION_JUMPING,
-# MOTION_KICKING, MOTION_SWORD, MOTION_RUNNING, MOTION_DANCING
-result = api.generate_animation(
-    model_image_url="https://...",
-    motion_type=api.MOTION_DANCING,
-    title="跳舞的模型"
-)
-cid = result["creationsId"]
-
-final = api.wait_for_completion(cid)
-```
-
-### 7. 纹理生成
-
-为白模/无纹理模型生成贴图。
-
-```python
-from hunyuan3dweb import Hunyuan3DAPIComplete
-
-api = Hunyuan3DAPIComplete()
-
-result = api.generate_texture(
-    white_model_url="https://...",
-    prompt="红色金属锈迹纹理",
-    title="纹理模型"
-)
-cid = result["creationsId"]
-
-final = api.wait_for_completion(cid)
-```
-
-### 8. 智能拓扑（减面 / Low Poly）
-
-降低现有模型的面数。
-
-```python
-from hunyuan3dweb import Hunyuan3DAPIComplete
-
-api = Hunyuan3DAPIComplete()
-
-result = api.generate_lowpoly(
-    model_url="https://...",
-    face_count=api.TOPO_LOW,  # 5000 / 18000 / 30000
-    topology_format="glb",    # "glb" 或 "obj"
-    title="低模模型"
-)
-cid = result["creationsId"]
-
-final = api.wait_for_completion(cid)
-```
-
-### 基础客户端（轻量）
-
-仅需图生3D和文生3D的用户可使用简化客户端：
-
-```python
-from hunyuan3dweb import Hunyuan3DAPI
-
-api = Hunyuan3DAPI()
-
-# 文生3D
-api.generate_text("一只猫")
-
-# 图生3D（需已有 resourceUrl）
-api.generate_3d(image_url="...")
-```
-
-### 显式指定 Cookie（多账户或自定义路径）
-
-```python
-from hunyuan3dweb import Hunyuan3DAPIComplete, load_cookies_from_file
-
-cookies = load_cookies_from_file("/path/to/cookies.txt")
-api = Hunyuan3DAPIComplete(cookies=cookies)
+hy3d auth status    # 登录体检
+hy3d quota          # 配额查询
 ```

 ## CLI 命令

- `hunyuan3dweb` - API CLI 工具（支持 quota / list / text / status 子命令）
- `hunyuan3dweb-login` - 浏览器登录（自动保存 Cookie）
- `hunyuan3dweb-sniffer` - API 拦截分析
- `hunyuan3dweb-generate` - 浏览器自动化生成
-
-### CLI 示例
-
-```bash
-# 查询配额
-hunyuan3dweb quota
-
-# 查询作品列表
-hunyuan3dweb list
-
-# 文生3D
-hunyuan3dweb text "一只红色的苹果"
-
-# 查询生成状态
-hunyuan3dweb status <creationsId>
-
-# 浏览器登录
-hunyuan3dweb-login
-
-# 本地图片生成（浏览器自动化）
-hunyuan3dweb-generate /path/to/image.png wait
-
-# API 拦截
-hunyuan3dweb-sniffer
+```
+hy3d [--json] [--cookies PATH] <command> [args...]
 ```

-## 文件说明
+| 命令 | 说明 | 示例 |
+|---|---|---|
+| `quota` | 查配额 | `hy3d quota` |
+| `list` | 作品列表 | `hy3d list --page 2` |
+| `count` | 作品统计 | `hy3d count` |
+| `user` | 用户信息 | `hy3d user` |
+| `status <id>` | 生成状态/详情 | `hy3d status <id> --wait` |
+| `formats <id>` | 可用下载格式 | `hy3d formats <id> --converted` |
+| `download <id>` | 下载模型 | `hy3d download <id> --format glb -o model.glb` |
+| `cancel <id>` | 取消任务 | `hy3d cancel <id>` |
+| `share <id>` | 生成分享 | `hy3d share <id>` |
+| `text "<prompt>"` | 文生 3D（4 配额） | `hy3d text "a red teapot" --style cyberpunk --wait` |
+| `image <file\|url>` | 图生 3D（本地自动上传） | `hy3d image ./photo.png --wait` |
+| `multi-view <img...>` | 多视角图生 3D（≥2 张） | `hy3d multi-view a.png b.png c.png --wait` |
+| `sketch <img> --prompt P` | 草图生 3D | `hy3d sketch sketch.png --prompt "a robot" --wait` |
+| `animate <img> --motion M` | 3D 动画 | `hy3d animate m.png --motion dancing --wait` |
+| `texture <img> --prompt P` | 白模上纹理 | `hy3d texture white.png --prompt "red metallic rust" --wait` |
+| `topo <img>` | 智能减面 | `hy3d topo model.png --faces 5000 --wait` |
+| `auth status\|login` | 登录体检/登录 | `hy3d auth status` |
+| `config` | 配置与环境变量 | `hy3d config` |
+
+生成命令都支持 `--wait`（提交后轮询到完成并输出模型链接）、`--style`、`--title`。
+所有命令支持 `--json`（机器可读输出）。
+
+**动作类型**（`animate`）：`capoeira falling jumping kicking sword running dancing`
+**纹理风格**（`--style`）：`sculpture qinghuaci china_style cartoon cyberpunk`
+**拓扑面数**（`topo --faces`）：`5000 18000 30000`
+**下载格式键**（`download --format`）：`glb obj mtl obj_url geometryGlb textureGlb textureObj image_url pbrImage pbrMetallicImage pbrRoughnessImage pbrNormalImage invisible_wall air_wall`，加 `--converted` 可转换出 `fbx stl usdz mp4 gif`
+
+### 退出码（agent 友好）
+
+| 码 | 含义 | 处理 |
+|---|---|---|
+| 0 | 成功 | — |
+| 1 | 环境/网络/参数/服务端 4xx | 看 stderr |
+| 2 | 认证失败（token 无效/过期） | 重新登录：`hy3d auth login` |
+| 3 | cookie 文件缺失 | 首次登录：`hy3d auth login` |
+
+## Python API
+
+```python
+from hy3d import Hunyuan3DAPIComplete
+
+api = Hunyuan3DAPIComplete()
+print(api.get_quota_info())            # {'remainQuota': 20, 'totalQuota': 20, ...}
+
+result = api.generate_from_text("a ceramic vase", style=api.STYLE_CYBERPUNK)
+cid = result["creationsId"]
+final = api.wait_for_completion(cid)   # 内置轮询，进度打 stdout
+
+# 本地图片 → COS 上传 → 图生 3D 全自动
+from hy3d import upload_image
+resource_url = upload_image("/path/to/photo.png")
+api.generate_from_image(resource_url, title="My Model")
+
+# 下载模型（原生 + 按需转换 fbx/stl/usdz/mp4/gif）
+urls = api.get_model_urls(cid, include_converted=True)   # 转换会调用 resourceConvert
+api.download_model(cid, "glb")           # → ./model.glb
+```
+
+完整 API 一览（`Hunyuan3DAPIComplete` / `hy3d/api_complete.py`）：
+
+| 方法 | 功能 |
+|---|---|
+| `generate_from_text` / `generate_from_image` | 文生 3D / 图生 3D |
+| `generate_from_multi_view` | 多视角图生 3D |
+| `generate_from_sketch` | 草图生 3D |
+| `generate_animation` / `generate_texture` | 动画 / 纹理 |
+| `generate_lowpoly` | 智能拓扑减面 |
+| `get_quota_info` / `get_creation_list` / `get_creation_count` | 配额 / 作品 / 统计 |
+| `get_generation_status` / `wait_for_completion` / `cancel_generation` | 任务管理 |
+| `get_model_urls` / `download_model` / `resource_convert` | 模型下载与格式转换 |
+| `get_upload_info` / `review_resource` | 资源上传与审核 |
+| `create_share` | 分享 |
+
+轻量版客户端 `Hunyuan3DAPI`（`hy3d/api.py`）只含文生/图生/配额/列表等核心接口。
+
+### 多账号 / 自定义 cookie
+
+```python
+from hy3d import Hunyuan3DAPIComplete, load_cookies_from_file
+api = Hunyuan3DAPIComplete(cookies=load_cookies_from_file("/path/to/cookies.txt"))
+```
+
+CLI 等价写法：`hy3d --cookies /path/to/cookies.txt quota`，或环境变量 `HY3D_COOKIES`。
+
+## 浏览器工具（可选）
+
+| 命令 | 用途 |
+|---|---|
+| `hy3d-login` | 邮箱验证码登录（无头，自动保存 cookie 与浏览器 profile） |
+| `hy3d-sniffer` | API 请求/响应抓包（`api_requests.log.json`） |
+| `hy3d-generate <img> [wait]` | 浏览器内图生 3D（走浏览器签名，适合对照验证） |
+
+需要 `pip install "hy3d[browser]"`（cloakbrowser + playwright）。
+
+## 配置与目录
+
+- cookie：`~/.config/hunyuan3dweb/cookies.txt`（路径保持不变，避免重新登录）
+- 浏览器 profile：`~/.config/hunyuan3dweb/profile`
+- 环境变量：`HY3D_COOKIES`（cookie 路径）、`HY3D_JSON=1`（等同 `--json`）
+
+## 文件结构

 | 文件 | 说明 |
-|------|------|
-| `hunyuan3dweb/api.py` | 基础 API 客户端（图生3D、文生3D） |
-| `hunyuan3dweb/api_complete.py` | 完整 API 客户端（所有生成模式） |
-| `hunyuan3dweb/sign.py` | 腾讯混元3D 签名算法 |
-| `hunyuan3dweb/cos_upload.py` | 纯 Python COS 上传工具 |
-| `hunyuan3dweb/config.py` | 用户配置路径管理 |
-| `hunyuan3dweb/cli.py` | CLI 入口 |
-| `hunyuan3dweb/browser/login.py` | 浏览器登录工具 |
-| `hunyuan3dweb/browser/sniffer.py` | API 拦截工具 |
-| `hunyuan3dweb/browser/generator.py` | 浏览器自动化生成 |
-| `doc/api.md` | API 接口文档 |
+|---|---|
+| `hy3d/cli.py` | CLI 入口（全部命令） |
+| `hy3d/api.py` | 轻量 API 客户端（图生 3D / 文生 3D） |
+| `hy3d/api_complete.py` | 完整 API 客户端（全部生成模式） |
+| `hy3d/sign.py` | 签名算法（HMAC-SHA256 + 密钥派生） |
+| `hy3d/cos_upload.py` | 纯 Python COS 上传（免浏览器） |
+| `hy3d/config.py` | 配置路径管理 |
+| `hy3d/browser/` | 登录 / 抓包 / 浏览器自动化工具 |
+
+## 相关文档
+
+- [逆向工程文档](README_REVERSE_ENGINEERING_CN.md) — 签名算法逆向过程与关键常量
+- [泛用性分析](UNIVERSALITY_ANALYSIS.md) — 算法能否复用到其他产品
+- [API 端点文档](doc/api_complete.md)