hunyuan3dweb/README.md

# hunyuan3dweb

Python API client and browser automation tools for Tencent Hunyuan 3D (https://3d.hunyuan.tencent.com/).

## Installation

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

For browser automation features:

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

## Login and Setup

First-time users need to log in via the browser. Cookies will be saved automatically:

```bash
hunyuan3dweb-login
```

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

Or programmatically via browser automation:

```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')}")
```

Or via pure Python upload:

```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="My Model")
```

### 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"
)
cid = result["creationsId"]

final = api.wait_for_completion(cid)
```

### 4. Multi-View Image-to-3D

Use multiple images from different angles to generate a more accurate 3D model.

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

### 5. Sketch-to-3D

```python
from hunyuan3dweb import Hunyuan3DAPIComplete

api = Hunyuan3DAPIComplete()

result = api.generate_from_sketch(
    sketch_url="https://...",
    prompt="a sketch of a robot",
    title="Sketch Robot"
)
cid = result["creationsId"]

final = api.wait_for_completion(cid)
```

### 6. Animation Generation

Requires a model image URL and a motion type.

```python
from hunyuan3dweb import Hunyuan3DAPIComplete

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 |