# 各生成节点使用方法

## 文/图生图
- 默认模型：`gpt-image-2.5`（≤1K，如 `1024x1024` 或比例 `"1:1"` / `"16:9"`）
- VIP 模型：`gpt-image-2-vip`（>1K 像素，如 `2048x2048`、`2048x1152`）
- API key：sk-b69877bd82c6412ca4872351f428d580
- 接口文档：Doc\gpt-image_doc.md
- 脚本：Tools\gpt_image_generate.py

### 模型选择规则（Agent / 人工均需遵守）
1. 输出边长 **≤1024**（含 `1024x1024` 及比例写法）：用默认 `gpt-image-2.5`。
2. 输出任一边 **>1024**（如 `2048x2048` UI 图集）：**必须**改用 VIP `gpt-image-2-vip`，并传像素写法（VIP **不支持** `"16:9"` 这类比例字符串）。
3. 脚本在 `--aspect-ratio` 为 `WxH` 且任一边 >1024 时：若当前模型不是 VIP 系列，会自动升为 `gpt-image-2-vip`；已是 `gpt-image-2-vip` / `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst` 则保留。
4. VIP 像素约束：边长为 16 的倍数、最大边 ≤3840、总像素约 0.64M–8.3M、长短边比 ≤3:1。
5. 当前账号下 `gpt-image-2.5-flare` 对 >1K 不可用，**不要默认使用 flare**。

### AI / 命令行调用
```bash
# 文生图（默认 1K / gpt-image-2.5）
python Tools/gpt_image_generate.py -p "一只边牧在草地上奔跑" -o AIClient/Assets/Generated/dog.png

# 大于 1K（如 2048）：用 VIP，传像素尺寸
python Tools/gpt_image_generate.py -p "UI sprite atlas" -o Tools/output/ui_atlas.png --aspect-ratio 2048x2048 --model gpt-image-2-vip

# 图生图（可多次传 --image）
python Tools/gpt_image_generate.py -p "保持构图，换成赛博朋克风格" -i ref.png -o out.png

# JSON 参数（适合 Agent / 流程编排）
python Tools/gpt_image_generate.py --json "{\"prompt\":\"城市夜景\",\"output\":\"out/city.png\"}" --result-only
python Tools/gpt_image_generate.py --json "{\"prompt\":\"UI图集\",\"output\":\"out/atlas.png\",\"aspectRatio\":\"2048x2048\",\"model\":\"gpt-image-2-vip\"}" --result-only
```

### 流程回调
- `--callback-url`：每个进度/结果事件 POST JSON
- `--callback-file`：覆盖写入 `{latest, history}` 状态文件
- 默认 stdout 输出 NDJSON 事件流，最后一行为最终结果

环境变量可选覆盖：`GRSAI_API_KEY`、`GPT_IMAGE_API_KEY`

## 腾讯混元3D（图生3D → GLB）
- 网站：`https://3d.hunyuan.tencent.com/`
- 脚本：`Tools/hunyuan_3d_generate.py`
- 模块：`Tools/hunyuan_3d/`（`auth.py` 微信登录 / `client.py` 图生自动化）
- 依赖：`Tools/requirements-hunyuan.txt`（`playwright` + 本机 Microsoft Edge）
  ```bash
  pip install -r Tools/requirements-hunyuan.txt
  playwright install msedge
  ```
- 会话目录：`Tools/data/hunyuan/`（`storage_state.json` 为登录凭证，已 gitignore）
- 环境变量：`HUNYUAN_SESSION_DIR`、`HUNYUAN_BROWSER_CHANNEL`（默认 `msedge`）

### 能力说明
1. 首期仅 **图生3D → GLB**。文生请先用上文「文/图生图」出图，再交给本脚本。
2. 未登录或凭证失效时，会 **弹出 Edge 微信扫码**（同步阻塞，最长 `--login-timeout` 秒），成功后自动续跑。
3. 面数：`--faces 50k|500k|1m`（默认 `50k`）。
4. 任务中间文件在 `Tools/data/hunyuan/jobs/<job_id>/`；最终 GLB 写到 `-o`。
5. 生成完成后须在 `Doc/ResDesc_Model.md` 登记资源（索引见 `Doc/ResDesc.md`）。

### AI / 命令行调用
```bash
# 查看登录状态
python Tools/hunyuan_3d_generate.py --status

# 预登录（弹出微信扫码）
python Tools/hunyuan_3d_generate.py --login

# 图生3D（未登录则中途自动弹微信）
python Tools/hunyuan_3d_generate.py -i ref.png -o Tools/output/prop.glb --faces 50k

# JSON / Agent
python Tools/hunyuan_3d_generate.py --json "{\"image\":\"ref.png\",\"output\":\"out/a.glb\",\"faces\":\"50k\"}" --result-only

# CI：禁止弹窗，未登录直接失败
python Tools/hunyuan_3d_generate.py -i ref.png -o out.glb --no-interactive-login
```

### 流程回调 / 事件
- `--callback-url` / `--callback-file` / NDJSON 与文生图脚本同模式
- 典型事件：`login_required` → `login_waiting` → `login_ok` → `stage` → `succeeded` / `failed`

## 高模减面与贴图烘焙
- 来源：复刻 `ClientTrunk/Tools/ModelTools`（`model_decimate` + `model_bake`）
- 目录：`Tools/model_tools/`（说明见 `Tools/model_tools/README.md`）
- 依赖：本机 **Blender**（推荐 5.0）；可选 Pillow（UV 观察图）；可选 UVPackmaster 4
- 默认路径：`D:\tools\Blender\blender-5.0.0-windows-x64\blender.exe`（可用 `BLENDER_EXE` / `BLENDER_PATH` / `--blender` 覆盖）

### 流程
```text
高模（FBX / GLB / glTF）
  -> 减面 + 重展 UV -> <名>_low.fbx
  -> Cycles selected-to-active 烘焙
  -> 低模 FBX + color / normal / ao / metallic / roughness PNG
```

### AI / 命令行调用
```bash
# 一键（推荐）：减面 + 烘焙
python Tools/model_tools/model_lowpoly_bake.py Tools/output/prop.glb -o Tools/output/prop_game --tris 5000 --size 2048

# 分步
python Tools/model_tools/model_decimate.py prop.glb --tris 5000 -o Tools/output/prop_low
python Tools/model_tools/model_bake.py prop.glb Tools/output/prop_low/prop_low.fbx -o Tools/output/prop_bake --size 2048

# JSON / Agent
python Tools/model_tools/model_lowpoly_bake.py --json "{\"high\":\"prop.glb\",\"out\":\"Tools/output/prop_game\",\"tris\":5000,\"size\":2048}" --result-only
```

与混元衔接：先 `hunyuan_3d_generate.py` 出高模 GLB，再对本脚本做低模烘焙；完成后登记 `Doc/ResDesc_Model.md`。