Initial commit

2026-05-24 21:47:44 +08:00
commit 2ce35563c4
20 changed files with 3698 additions and 0 deletions
--- a/README_CN.md
+++ b/README_CN.md
@@ -0,0 +1,291 @@
+# hunyuan3dweb
+
+腾讯混元3D (https://3d.hunyuan.tencent.com/) 的 Python API 客户端与浏览器自动化工具。
+
+## 安装
+
+```bash
+pip install -e .
+```
+
+如需浏览器自动化功能：
+
+```bash
+pip install -e ".[browser]"
+```
+
+## 登录与配置
+
+第一次使用需要先通过浏览器登录，系统会自动保存 Cookie：
+
+```bash
+hunyuan3dweb-login
+```
+
+登录成功后：
+- 浏览器 Profile 保存到 `~/.config/hunyuan3dweb/profile`
+- Cookie 自动提取到 `~/.config/hunyuan3dweb/cookies.txt`
+
+之后写 Python 脚本无需再处理 Cookie，库会自动读取。
+
+## Python 脚本调用
+
+### 快速开始（自动读取默认 Cookie）
+
+```python
+from hunyuan3dweb import Hunyuan3DAPIComplete
+
+api = Hunyuan3DAPIComplete()
+
+# 查配额
+quota = api.get_quota_info()
+print(f"剩余: {quota['remainQuota']}/{quota['totalQuota']}")
+```
+
+### 1. 文生3D
+
+最简单的模式，无需上传图片。
+
+```python
+from hunyuan3dweb import Hunyuan3DAPIComplete
+
+api = Hunyuan3DAPIComplete()
+
+# 提交生成任务
+result = api.generate_from_text("一只陶瓷花瓶", title="测试")
+cid = result["creationsId"]
+
+# 轮询直到完成（内置轮询，自动打印进度）
+final = api.wait_for_completion(cid)
+print("生成完成")
+```
+
+**完整流水线：文生3D → 提取下载链接**
+
+```python
+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（本地文件）
+
+本地图片文件需通过浏览器自动化工具上传。纯 API 客户端无法直接上传图片，因为腾讯 COS 临时凭证需要浏览器端解密。
+
+```bash
+hunyuan3dweb-generate /path/to/image.png wait
+```
+
+或通过浏览器自动化脚本：
+
+```python
+from hunyuan3dweb.browser.generator import generate_3d
+
+result = generate_3d("/path/to/image.png", wait_for_complete=True)
+print(f"模型地址: {result.get('modelUrl')}")
+```
+
+### 3. 图生3D（API，已有 resourceUrl）
+
+如果你已经有 `resourceUrl`（例如之前通过浏览器上传过），可直接调用 API：
+
+```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="我的模型"
+)
+cid = result["creationsId"]
+
+final = api.wait_for_completion(cid)
+```
+
+### 4. 多图视角生3D（多视图）
+
+使用多张不同角度的图片生成更精确的 3D 模型。
+
+```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="多视图模型"
+)
+cid = result["creationsId"]
+
+final = api.wait_for_completion(cid)
+```
+
+### 5. 草图生3D
+
+```python
+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 和动作类型。
+
+```python
+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. 纹理生成
+
+为白模/无纹理模型生成贴图。
+
+```python
+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）
+
+降低现有模型的面数。
+
+```python
+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的用户可使用简化客户端：
+
+```python
+from hunyuan3dweb import Hunyuan3DAPI
+
+api = Hunyuan3DAPI()
+
+# 文生3D
+api.generate_text("一只猫")
+
+# 图生3D（需已有 resourceUrl）
+api.generate_3d(image_url="...")
+```
+
+### 显式指定 Cookie（多账户或自定义路径）
+
+```python
+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 示例
+
+```bash
+# 查询配额
+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/config.py` | 用户配置路径管理 |
+| `hunyuan3dweb/cli.py` | CLI 入口 |
+| `hunyuan3dweb/browser/login.py` | 浏览器登录工具 |
+| `hunyuan3dweb/browser/sniffer.py` | API 拦截工具 |
+| `hunyuan3dweb/browser/generator.py` | 浏览器自动化生成 |
+| `doc/api.md` | API 接口文档 |