Initial commit
This commit is contained in:
291
README.md
Normal file
291
README.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user