bf4e1e5755
- feat(cos): add cos_upload.py for direct file upload without browser
- implements COS V1 signature algorithm with temporary credentials
- upload_image() pipeline: get_upload_info → sign → PUT to COS
- feat(api): auto-load cookies from file when cookies arg is omitted
- both Hunyuan3DAPI and Hunyuan3DAPIComplete now fall back to
~/.config/hunyuan3dweb/cookies.txt automatically
- fix(login): strengthen login-state detection using both URL and DOM
- checks "login" not in page.url AND no login button on page
- docs: update README / README_CN with COS upload examples
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
305 lines
6.8 KiB
Markdown
305 lines
6.8 KiB
Markdown
# 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（本地文件）
|
||
|
||
本地图片文件可通过浏览器自动化工具上传，也可使用纯 Python 的 COS 上传模块先拿到 `resourceUrl` 再走 API。
|
||
|
||
```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')}")
|
||
```
|
||
|
||
或通过纯 Python 上传：
|
||
|
||
```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：
|
||
|
||
```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/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 接口文档 |
|