KawasakiAkasei/hy3d
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: rename project to hy3d, full CLI overhaul

Browse Source 
- 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
This commit is contained in:
KawasakiAkasei
2026-08-15 22:31:50 +08:00
parent 956b015ee0
commit acfe5e7ac2
23 changed files with 842 additions and 862 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+119 -259
View File
@@ -1,304 +1,164 @@
# hunyuan3dweb
# hy3d
Python API client and browser automation tools for Tencent Hunyuan 3D (https://3d.hunyuan.tencent.com/).
非官方腾讯混元 3D CLI 与 Python API 客户端（[3d.hunyuan.tencent.com](https://3d.hunyuan.tencent.com/)）。
## Installation
纯 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]" # 额外安装浏览器工具（登录/抓包/浏览器自动化）
```
For browser automation features:
不安装也能用——克隆仓库后直接用源码跑（无需 `pip install`）：
```bash
pip install -e ".[browser]"
cd hy3d
PYTHONPATH=$PWD python3 -m hy3d.cli quota
```
## Login and Setup
## 快速开始
First-time users need to log in via the browser. Cookies will be saved automatically:
首次使用需要登录一次（**在真实终端运行**，邮箱验证码登录，无头浏览器）：
```bash
hunyuan3dweb-login
hy3d auth login
# → 按提示: 输邮箱 → 收验证码 → 输验证码
# → cookie 自动保存到 ~/.config/hunyuan3dweb/cookies.txt
```
After successful login:
- Browser profile is saved to `~/.config/hunyuan3dweb/profile`
- Cookies are automatically extracted to `~/.config/hunyuan3dweb/cookies.txt`
Subsequent Python scripts will read cookies automatically — no manual configuration needed.
## Python Script Usage
### Quick Start (Auto-read Default Cookie)
```python
from hunyuan3dweb import Hunyuan3DAPIComplete
api = Hunyuan3DAPIComplete()
# Check quota
quota = api.get_quota_info()
print(f"Remaining: {quota['remainQuota']}/{quota['totalQuota']}")
```
### 1. Text-to-3D
The simplest mode. No image upload required.
```python
from hunyuan3dweb import Hunyuan3DAPIComplete
api = Hunyuan3DAPIComplete()
# Submit generation job
result = api.generate_from_text("a ceramic vase", title="Test")
cid = result["creationsId"]
# Poll until completion (built-in polling with progress output)
final = api.wait_for_completion(cid)
print("Generation complete")
```
**Full pipeline: Text-to-3D → Extract Download Links**
```python
from hunyuan3dweb import Hunyuan3DAPIComplete
api = Hunyuan3DAPIComplete()
job = api.generate_from_text(
"cyberpunk style mechanical dog",
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"Image: {urls.get('image_url')}")
```
### 2. Image-to-3D (Local File)
For local image files, you can use either the browser automation tool or the pure Python COS uploader to obtain a `resourceUrl` and then call the API.
验证登录与配额：
```bash
hunyuan3dweb-generate /path/to/image.png wait
hy3d auth status # 登录体检
hy3d quota # 配额查询
```
Or programmatically via browser automation:
## CLI 命令
```python
from hunyuan3dweb.browser.generator import generate_3d
result = generate_3d("/path/to/image.png", wait_for_complete=True)
print(f"Model URL: {result.get('modelUrl')}")
```
hy3d [--json] [--cookies PATH] <command> [args...]
```
Or via pure Python upload:
| 命令 | 说明 | 示例 |
|---|---|---|
| `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 hunyuan3dweb.cos_upload import upload_image
from hunyuan3dweb import Hunyuan3DAPIComplete
resource_url = upload_image("/path/to/image.png")
from hy3d import Hunyuan3DAPIComplete
api = Hunyuan3DAPIComplete()
result = api.generate_from_image(resource_url, title="My Model")
```
print(api.get_quota_info()) # {'remainQuota': 20, 'totalQuota': 20, ...}
### 3. Image-to-3D (API with Existing resourceUrl)
If you already have a `resourceUrl` (e.g. from a previous browser upload), use the pure API client:
```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="My Model"
)
result = api.generate_from_text("a ceramic vase", style=api.STYLE_CYBERPUNK)
cid = result["creationsId"]
final = api.wait_for_completion(cid) # 内置轮询，进度打 stdout
final = api.wait_for_completion(cid)
# 本地图片 → 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
```
### 4. Multi-View Image-to-3D
完整 API 一览（`Hunyuan3DAPIComplete` / `hy3d/api_complete.py`）：
Use multiple images from different angles to generate a more accurate 3D model.
| 方法 | 功能 |
|---|---|
| `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 hunyuan3dweb import Hunyuan3DAPIComplete
api = Hunyuan3DAPIComplete()
result = api.generate_from_multi_view(
image_urls=[
"https://.../front.png",
"https://.../side.png",
"https://.../back.png",
],
title="Multi-View Model"
)
cid = result["creationsId"]
final = api.wait_for_completion(cid)
from hy3d import Hunyuan3DAPIComplete, load_cookies_from_file
api = Hunyuan3DAPIComplete(cookies=load_cookies_from_file("/path/to/cookies.txt"))
```
### 5. Sketch-to-3D
CLI 等价写法：`hy3d --cookies /path/to/cookies.txt quota`，或环境变量 `HY3D_COOKIES`。
```python
from hunyuan3dweb import Hunyuan3DAPIComplete
## 浏览器工具（可选）
api = Hunyuan3DAPIComplete()
| 命令 | 用途 |
|---|---|
| `hy3d-login` | 邮箱验证码登录（无头，自动保存 cookie 与浏览器 profile） |
| `hy3d-sniffer` | API 请求/响应抓包（`api_requests.log.json`） |
| `hy3d-generate <img> [wait]` | 浏览器内图生 3D（走浏览器签名，适合对照验证） |
result = api.generate_from_sketch(
sketch_url="https://...",
prompt="a sketch of a robot",
title="Sketch Robot"
)
cid = result["creationsId"]
需要 `pip install "hy3d[browser]"`（cloakbrowser + playwright）。
final = api.wait_for_completion(cid)
```
## 配置文件与目录
### 6. Animation Generation
- cookie：`~/.config/hunyuan3dweb/cookies.txt`（路径保持不变，避免重新登录）
- 浏览器 profile：`~/.config/hunyuan3dweb/profile`
- 环境变量：`HY3D_COOKIES`（cookie 路径）、`HY3D_JSON=1`（等同 `--json`）
Requires a model image URL and a motion type.
## 文件结构
```python
from hunyuan3dweb import Hunyuan3DAPIComplete
| 文件 | 说明 |
|---|---|
| `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/` | 登录 / 抓包 / 浏览器自动化工具 |
api = Hunyuan3DAPIComplete()
## 相关文档
# Available motions: 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="Dancing Model"
)
cid = result["creationsId"]
final = api.wait_for_completion(cid)
```
### 7. Texture Generation
Apply texture to a white/untexured model.
```python
from hunyuan3dweb import Hunyuan3DAPIComplete
api = Hunyuan3DAPIComplete()
result = api.generate_texture(
white_model_url="https://...",
prompt="red metallic texture with rust",
title="Textured Model"
)
cid = result["creationsId"]
final = api.wait_for_completion(cid)
```
### 8. Smart Topology (Decimation / Low Poly)
Reduce polygon count of an existing model.
```python
from hunyuan3dweb import Hunyuan3DAPIComplete
api = Hunyuan3DAPIComplete()
result = api.generate_lowpoly(
model_url="https://...",
face_count=api.TOPO_LOW, # 5000, 18000, or 30000
topology_format="glb", # "glb" or "obj"
title="Low Poly Model"
)
cid = result["creationsId"]
final = api.wait_for_completion(cid)
```
### Basic Client (Lightweight)
For users who only need image-to-3D and text-to-3D:
```python
from hunyuan3dweb import Hunyuan3DAPI
api = Hunyuan3DAPI()
# Text-to-3D
api.generate_text("a cat")
# Image-to-3D (requires existing resourceUrl)
api.generate_3d(image_url="...")
```
### Explicit Cookie Path (Multi-account or Custom Path)
```python
from hunyuan3dweb import Hunyuan3DAPIComplete, load_cookies_from_file
cookies = load_cookies_from_file("/path/to/cookies.txt")
api = Hunyuan3DAPIComplete(cookies=cookies)
```
## CLI Commands
- `hunyuan3dweb` - API CLI tool (supports quota / list / text / status subcommands)
- `hunyuan3dweb-login` - Browser login (auto-saves cookies)
- `hunyuan3dweb-sniffer` - API request/response sniffer
- `hunyuan3dweb-generate` - Browser automation for generation
### CLI Examples
```bash
# Check quota
hunyuan3dweb quota
# List creations
hunyuan3dweb list
# Text-to-3D
hunyuan3dweb text "a red apple"
# Check generation status
hunyuan3dweb status <creationsId>
# Browser login
hunyuan3dweb-login
# Generate from local image (browser automation)
hunyuan3dweb-generate /path/to/image.png wait
# Sniff API traffic
hunyuan3dweb-sniffer
```
## File Reference
| File | Description |
|------|-------------|
| `hunyuan3dweb/api.py` | Basic API client (image2model, text2model) |
| `hunyuan3dweb/api_complete.py` | Full API client (all generation modes) |
| `hunyuan3dweb/sign.py` | Tencent Hunyuan 3D signing algorithm |
| `hunyuan3dweb/cos_upload.py` | Pure Python COS upload helper |
| `hunyuan3dweb/config.py` | User config path management |
| `hunyuan3dweb/cli.py` | CLI entry point |
| `hunyuan3dweb/browser/login.py` | Browser login tool |
| `hunyuan3dweb/browser/sniffer.py` | API sniffer tool |
| `hunyuan3dweb/browser/generator.py` | Browser automation generator |
| `doc/api.md` | API endpoint documentation |
- [reverse engineering 文档](README_REVERSE_ENGINEERING.md) — 签名算法逆向过程与关键常量
- [泛用性分析](UNIVERSALITY_ANALYSIS.md) — 算法能否复用到其他产品
- [API 端点文档](doc/api.md)