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
164 lines
6.7 KiB
Markdown
164 lines
6.7 KiB
Markdown
# hy3d
|
||
|
||
非官方腾讯混元 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 hy3d # 纯 API 客户端
|
||
pip install "hy3d[browser]" # 额外安装浏览器工具（登录/抓包/浏览器自动化）
|
||
```
|
||
|
||
不安装也能用——克隆仓库后直接用源码跑（无需 `pip install`）：
|
||
|
||
```bash
|
||
cd hy3d
|
||
PYTHONPATH=$PWD python3 -m hy3d.cli quota
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
首次使用需要登录一次（**在真实终端运行**，邮箱验证码登录，无头浏览器）：
|
||
|
||
```bash
|
||
hy3d auth login
|
||
# → 按提示: 输邮箱 → 收验证码 → 输验证码
|
||
# → cookie 自动保存到 ~/.config/hunyuan3dweb/cookies.txt
|
||
```
|
||
|
||
验证登录与配额：
|
||
|
||
```bash
|
||
hy3d auth status # 登录体检
|
||
hy3d quota # 配额查询
|
||
```
|
||
|
||
## CLI 命令
|
||
|
||
```
|
||
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`）
|
||
|
||
## 文件结构
|
||
|
||
| 文件 | 说明 |
|
||
|---|---|
|
||
| `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/` | 登录 / 抓包 / 浏览器自动化工具 |
|
||
|
||
## 相关文档
|
||
|
||
- [reverse engineering 文档](README_REVERSE_ENGINEERING.md) — 签名算法逆向过程与关键常量
|
||
- [泛用性分析](UNIVERSALITY_ANALYSIS.md) — 算法能否复用到其他产品
|
||
- [API 端点文档](doc/api.md) |