skills/meshy-3d-gen/SKILL.md

name, description

name	description
meshy-3d-gen	调用 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 标准库，无额外依赖）：

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

示例：

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

推荐模板：

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 场景里的占位模型节点