# 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 前端签名算法的逆向实现，与腾讯无关。仅供个人学习与自动化使用。

## 安装

本项目**不发布到 PyPI**——通过克隆仓库安装（推荐先用 [pipx](https://pipx.pypa.io/) 隔离环境；或用 venv + pip）：

```bash
# 1. 克隆仓库
git clone https://gitea.akasei.top/KawasakiAkasei/hy3d.git
cd hy3d

# 2. 安装（pipx 装进独立 venv，hy3d 命令进 PATH）
pipx install ".[browser]"

# 3. 验证
hy3d auth status
```

不想保留仓库副本也能直接装：

```bash
pipx install "git+https://gitea.akasei.top/KawasakiAkasei/hy3d.git"
```

> **「browser」扩展**提供登录/抓包/浏览器自动化（cloakbrowser + playwright）；
> 只调用 API 可以省略。已装过纯客户端、想补 browser 扩展：
> `cd hy3d && pipx install --force ".[browser]"`。
> **私有仓库**场景：clone 用 SSH —— `git clone git@gitea.akasei.top:KawasakiAkasei/hy3d.git`；git 直装同理。

不安装也能用——直接以源码方式运行（无需 pip install）：

```bash
cd hy3d
PYTHONPATH=$PWD python3 -m hy3d.cli quota
```

## 快速开始

首次使用需要登录一次（**在真实终端运行**，邮箱验证码登录，无头浏览器）：

```bash
hy3d auth login
# → 按提示: 输邮箱 → 收验证码 → 输验证码
# → cookie 自动保存到 ~/.config/hy3d/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（走浏览器签名，适合对照验证） |

需要 browser 扩展（安装时加 `[browser]`，见上文安装节）。

## 配置与目录

- cookie：`~/.config/hy3d/cookies.txt`（全新目录，cookie 已随搬迁保留）
- 浏览器 profile：`~/.config/hy3d/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/` | 登录 / 抓包 / 浏览器自动化工具 |

## Claude Code Skill（可选）

`skill/run-hy3d/` 附带一个 Claude Code skill：让 agent 直接驱动 `hy3d`（查配额、文生 3D、下载模型、诊断登录状态与退出码）。安装：

```bash
./skill/install.sh        # 安装到 ~/.claude/skills/run-hy3d
```

新会话中可用 `/run-hy3d` 调用，或当描述命中时自动加载。卸载：`rm -rf ~/.claude/skills/run-hy3d`。

## 相关文档

- [逆向工程文档](README_REVERSE_ENGINEERING_CN.md) — 签名算法逆向过程与关键常量
- [泛用性分析](UNIVERSALITY_ANALYSIS.md) — 算法能否复用到其他产品
- [API 端点文档](doc/api_complete.md)