KawasakiAkasei
bd987a2222
- skill/run-hy3d/SKILL.md: user-level skill now versioned in repo - skill/install.sh: one-command install to ~/.claude/skills/run-hy3d - README/README_CN: document skill install/uninstall
7.8 KiB
hy3d
非官方腾讯混元 3D CLI 与 Python API 客户端（3d.hunyuan.tencent.com）。
纯 Python HTTP 调用腾讯混元 3D 的 AI 能力：文生 3D、图生 3D、多视角、草图、动画、纹理、智能拓扑减面，以及配额查询、作品管理、模型下载（GLB/OBJ/FBX/STL/USDZ/MP4/GIF）。
⚠️ 非官方项目：这是对混元 3D Web 前端签名算法的逆向实现，与腾讯无关。仅供个人学习与自动化使用。
安装
本项目不发布到 PyPI——通过克隆仓库安装（推荐先用 pipx 隔离环境；或用 venv + pip）：
# 1. 克隆仓库
git clone https://gitea.akasei.top/KawasakiAkasei/hy3d.git
cd hy3d
# 2. 安装（pipx 装进独立 venv，hy3d 命令进 PATH）
pipx install ".[browser]"
# 3. 验证
hy3d auth status
不想保留仓库副本也能直接装：
pipx install "git+https://gitea.akasei.top/KawasakiAkasei/hy3d.git"
「browser」扩展提供登录/抓包/浏览器自动化（cloakbrowser + playwright）； 只调用 API 可以省略。已装过纯客户端、想补 browser 扩展：
cd hy3d && pipx install --force ".[browser]"。 私有仓库场景：clone 用 SSH ——git clone git@gitea.akasei.top:KawasakiAkasei/hy3d.git；git 直装同理。
不安装也能用——直接以源码方式运行（无需 pip install）：
cd hy3d
PYTHONPATH=$PWD python3 -m hy3d.cli quota
快速开始
首次使用需要登录一次（在真实终端运行，邮箱验证码登录，无头浏览器）：
hy3d auth login
# → 按提示: 输邮箱 → 收验证码 → 输验证码
# → cookie 自动保存到 ~/.config/hy3d/cookies.txt
验证登录与配额：
hy3d auth status # 登录体检
hy3d quota # 配额查询
CLI 命令
hy3d [--json] [--cookies PATH] <command> [args...]
| 命令 | 说明 | 示例 |
|---|---|---|
quota |
查配额 | hy3d quota |
list |
作品列表 | hy3d list --page 2 |
count |
作品统计 | hy3d count |
user |
用户信息 | hy3d user |
status <id> |
生成状态/详情 | hy3d status <id> --wait |
formats <id> |
可用下载格式 | hy3d formats <id> --converted |
download <id> |
下载模型 | hy3d download <id> --format glb -o model.glb |
cancel <id> |
取消任务 | hy3d cancel <id> |
share <id> |
生成分享 | hy3d share <id> |
text "<prompt>" |
文生 3D（4 配额） | hy3d text "a red teapot" --style cyberpunk --wait |
image <file|url> |
图生 3D（本地自动上传） | hy3d image ./photo.png --wait |
multi-view <img...> |
多视角图生 3D（≥2 张） | hy3d multi-view a.png b.png c.png --wait |
sketch <img> --prompt P |
草图生 3D | hy3d sketch sketch.png --prompt "a robot" --wait |
animate <img> --motion M |
3D 动画 | hy3d animate m.png --motion dancing --wait |
texture <img> --prompt P |
白模上纹理 | hy3d texture white.png --prompt "red metallic rust" --wait |
topo <img> |
智能减面 | hy3d topo model.png --faces 5000 --wait |
auth status|login |
登录体检/登录 | hy3d auth status |
config |
配置与环境变量 | hy3d config |
生成命令都支持 --wait（提交后轮询到完成并输出模型链接）、--style、--title。
所有查询命令支持 --json（机器可读输出）。
动作类型（animate）：capoeira falling jumping kicking sword running dancing
纹理风格（--style）：sculpture qinghuaci china_style cartoon cyberpunk
拓扑面数（topo --faces）：5000 18000 30000
下载格式键（download --format）：glb obj mtl obj_url geometryGlb textureGlb textureObj image_url pbrImage pbrMetallicImage pbrRoughnessImage pbrNormalImage invisible_wall air_wall，加 --converted 可转换出 fbx stl usdz mp4 gif
退出码（agent 友好）
| 码 | 含义 | 处理 |
|---|---|---|
| 0 | 成功 | — |
| 1 | 环境/网络/参数/服务端 4xx | 看 stderr |
| 2 | 认证失败（token 无效/过期） | 重新登录：hy3d auth login |
| 3 | cookie 文件缺失 | 首次登录：hy3d auth login |
Python API
from hy3d import Hunyuan3DAPIComplete
api = Hunyuan3DAPIComplete()
print(api.get_quota_info()) # {'remainQuota': 20, 'totalQuota': 20, ...}
result = api.generate_from_text("a ceramic vase", style=api.STYLE_CYBERPUNK)
cid = result["creationsId"]
final = api.wait_for_completion(cid) # 内置轮询，进度打 stdout
# 本地图片 → COS 上传 → 图生 3D 全自动
from hy3d import upload_image
resource_url = upload_image("/path/to/photo.png")
api.generate_from_image(resource_url, title="My Model")
# 下载模型（原生 + 按需转换 fbx/stl/usdz/mp4/gif）
urls = api.get_model_urls(cid, include_converted=True) # 转换会调用 resourceConvert
api.download_model(cid, "glb") # → ./model.glb
完整 API 一览（Hunyuan3DAPIComplete / hy3d/api_complete.py）：
| 方法 | 功能 |
|---|---|
generate_from_text / generate_from_image |
文生 3D / 图生 3D |
generate_from_multi_view |
多视角图生 3D |
generate_from_sketch |
草图生 3D |
generate_animation / generate_texture |
动画 / 纹理 |
generate_lowpoly |
智能拓扑减面 |
get_quota_info / get_creation_list / get_creation_count |
配额 / 作品 / 统计 |
get_generation_status / wait_for_completion / cancel_generation |
任务管理 |
get_model_urls / download_model / resource_convert |
模型下载与格式转换 |
get_upload_info / review_resource |
资源上传与审核 |
create_share |
分享 |
轻量版客户端 Hunyuan3DAPI（hy3d/api.py）只含文生/图生/配额/列表等核心接口。
多账号 / 自定义 cookie
from hy3d import Hunyuan3DAPIComplete, load_cookies_from_file
api = Hunyuan3DAPIComplete(cookies=load_cookies_from_file("/path/to/cookies.txt"))
CLI 等价写法：hy3d --cookies /path/to/cookies.txt quota，或环境变量 HY3D_COOKIES。
浏览器工具（可选）
| 命令 | 用途 |
|---|---|
hy3d-login |
邮箱验证码登录（无头，自动保存 cookie 与浏览器 profile） |
hy3d-sniffer |
API 请求/响应抓包（api_requests.log.json） |
hy3d-generate <img> [wait] |
浏览器内图生 3D（走浏览器签名，适合对照验证） |
需要 browser 扩展（安装时加 [browser]，见上文安装节）。
配置文件与目录
- cookie：
~/.config/hy3d/cookies.txt（全新目录，cookie 已随搬迁保留） - 浏览器 profile：
~/.config/hy3d/profile - 环境变量：
HY3D_COOKIES（cookie 路径）、HY3D_JSON=1（等同--json）
文件结构
| 文件 | 说明 |
|---|---|
hy3d/cli.py |
CLI 入口（全部命令） |
hy3d/api.py |
轻量 API 客户端（图生 3D / 文生 3D） |
hy3d/api_complete.py |
完整 API 客户端（全部生成模式） |
hy3d/sign.py |
签名算法（HMAC-SHA256 + 密钥派生） |
hy3d/cos_upload.py |
纯 Python COS 上传（免浏览器） |
hy3d/config.py |
配置路径管理 |
hy3d/browser/ |
登录 / 抓包 / 浏览器自动化工具 |
Claude Code Skill（可选）
skill/run-hy3d/ 附带一个 Claude Code skill：让 agent 直接驱动 hy3d（查配额、文生 3D、下载模型、诊断登录状态与退出码）。安装：
./skill/install.sh # 安装到 ~/.claude/skills/run-hy3d
新会话中可用 /run-hy3d 调用，或当描述命中时自动加载。卸载：rm -rf ~/.claude/skills/run-hy3d。
相关文档
- reverse engineering 文档 — 签名算法逆向过程与关键常量
- 泛用性分析 — 算法能否复用到其他产品
- API 端点文档