---
name: meshy-3d-gen
description: 调用 Meshy AI API 从文本生成 3D 模型（text-to-3d：preview→refine→下载 GLB）。当用户要求生成/优化 3D 模型、替换 glb 资产、用 AI 建模时调用。
---

# Meshy 3D 模型生成

调用 Meshy AI OpenAPI v2，通过文本生成 lowpoly 3D 模型，输出 `.glb` 文件。

## API Key

优先读环境变量 `MESHY_API_KEY`，否则读 `~/.config/meshy_api_key`。绝不硬编码到代码或写入 git。

## 脚本

`scripts/meshy_gen.py` 封装完整流程（Python 3 标准库，无额外依赖）：

```bash
python3 ~/.codex/skills/meshy-3d-gen/scripts/meshy_gen.py "<prompt>" "<输出.glb>" "[texture_prompt]"
```

示例：

```bash
python3 ~/.codex/skills/meshy-3d-gen/scripts/meshy_gen.py \
  "stylized low-poly Japanese castle, white walls, dark tiled roof, gold trim, game asset, fantasy" \
  "art/castle.glb" \
  "flat colors, stylized texture, white plaster, dark roof tiles, gold trim, no photorealism"
```

脚本自动执行：创建 preview 任务 → 轮询（每 5s）→ 创建 refine 任务（PBR 贴图、移除烘焙光照）→ 轮询 → 下载 GLB。

## 计费

preview 20 credits + refine 10 credits = **30 credits/次**。重试也照扣，所以 prompt 要一次写准；先用免费/轻量方式确认方向再跑。

## 风格规范（本项目）

生成 Taiko5 资产时必须：

- `model_type: lowpoly` 保持风格统一（脚本已固定）
- prompt 包含关键词：`stylized, low-poly, game asset`
- 禁用 `realistic, photorealistic`
- 贴图提示强调：`flat colors, stylized texture, no photorealism`

## 详细提示词规范（必读）

Meshy 对提示词细节非常敏感，通用描述会生成简单几何块。每次生成前必须按以下清单写足细节：

1. **历史原型/时代风格**：点名真实城堡或时代，例如 `Himeji-style`、`Azuchi-style`、`Sengoku period`
2. **层数与内部结构**：明确 `X visible roof tiers` 和 `X stories inside`，防止只生成一层
3. **屋顶细节**：`hipped-and-gabled roofs (irimoya)`、`curved eaves`、`shachihoko ridge ornaments`、`chidori-hafu gable dormers`
4. **墙体与石基**：`white plaster walls`、`dark kawara tiled roofs`、`large sloping stone base (ishigaki)`、`red wooden pillars`
5. **局部构件**：门窗、斗拱、栏杆、金饰、角楼、破风、瓦当
6. **姿态与用途**：`symmetrical front`、`standing upright on flat ground`、`suitable as a map landmark`、`game asset`
7. **负面项**：`no photorealism`、`no realistic textures`、`no extra text or watermark`
8. **贴图提示**：单独给出 `flat colors, stylized texture, white plaster, dark roof tiles, gold trim, red accents, no photorealism`

推荐模板：

```text
stylized low-poly Japanese castle tenshu in Himeji style, four visible roof tiers, five stories inside,
white plaster walls, dark charcoal kawara curved roofs with gold trim, hipped-and-gabled (irimoya) roofs,
shachihoko ridge ornaments, red wooden pillars, large sloping stone base (ishigaki), chidori-hafu gable
dormers, small corner turrets, symmetrical front, standing upright on flat ground, game asset, fantasy,
historical Japanese castle, suitable as a map landmark
```

## 注意事项

- Meshy 服务端只保留下载链接 3 天，生成后立即下载
- 失败模式：401 认证失败、402 积分不足、429 频率超限
- 生成的 GLB 可直接替换 Taiko5 场景里的占位模型节点