292 lines
6.6 KiB
Markdown
292 lines
6.6 KiB
Markdown
# 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, use the browser automation tool. The pure API client cannot upload images directly because Tencent COS requires browser-side decryption of temporary credentials.
|
|
|
|
```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')}")
|
|
```
|
|
|
|
### 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/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 |
|