# hunyuan3dweb

腾讯混元3D (https://3d.hunyuan.tencent.com/) 的 Python API 客户端与浏览器自动化工具。

## 安装

```bash
pip install -e .
```

如需浏览器自动化功能：

```bash
pip install -e ".[browser]"
```

## 登录与配置

第一次使用需要先通过浏览器登录，系统会自动保存 Cookie：

```bash
hunyuan3dweb-login
```

登录成功后：
- 浏览器 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)
```

## 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
```

## 文件说明

| 文件 | 说明 |
|------|------|
| `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 接口文档 |