hunyuan3dweb

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

Installation

pip install -e .

For browser automation features:

pip install -e ".[browser]"

Login and Setup

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

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)

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.

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

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.

hunyuan3dweb-generate /path/to/image.png wait

Or programmatically via browser automation:

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:

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:

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.

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

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.

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.

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.

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:

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)

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

# 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