hunyuan3dweb/README_CN.md

hunyuan3dweb

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

安装

pip install -e .

如需浏览器自动化功能：

pip install -e ".[browser]"

登录与配置

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

hunyuan3dweb-login

登录成功后：

• 浏览器 Profile 保存到 ~/.config/hunyuan3dweb/profile
• Cookie 自动提取到 ~/.config/hunyuan3dweb/cookies.txt

之后写 Python 脚本无需再处理 Cookie，库会自动读取。

Python 脚本调用

快速开始（自动读取默认 Cookie）

from hunyuan3dweb import Hunyuan3DAPIComplete

api = Hunyuan3DAPIComplete()

# 查配额
quota = api.get_quota_info()
print(f"剩余: {quota['remainQuota']}/{quota['totalQuota']}")

1. 文生3D

最简单的模式，无需上传图片。

from hunyuan3dweb import Hunyuan3DAPIComplete

api = Hunyuan3DAPIComplete()

# 提交生成任务
result = api.generate_from_text("一只陶瓷花瓶", title="测试")
cid = result["creationsId"]

# 轮询直到完成（内置轮询，自动打印进度）
final = api.wait_for_completion(cid)
print("生成完成")

完整流水线：文生3D → 提取下载链接

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。

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

或通过浏览器自动化脚本：

from hunyuan3dweb.browser.generator import generate_3d

result = generate_3d("/path/to/image.png", wait_for_complete=True)
print(f"模型地址: {result.get('modelUrl')}")

或通过纯 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：

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 模型。

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

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 和动作类型。

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. 纹理生成

为白模/无纹理模型生成贴图。

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）

降低现有模型的面数。

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的用户可使用简化客户端：

from hunyuan3dweb import Hunyuan3DAPI

api = Hunyuan3DAPI()

# 文生3D
api.generate_text("一只猫")

# 图生3D（需已有 resourceUrl）
api.generate_3d(image_url="...")

显式指定 Cookie（多账户或自定义路径）

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 示例

# 查询配额
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 接口文档