/meshyai

name: meshyai
description: Generate custom 3D models from text or images using Meshy AI, then auto-rig and animate them for Three.js games. The preferred source for all 3D game assets. Use when the user says "generate a 3D model", "create a character model", "use Meshy", or needs a custom GLB model that doesn't exist in free libraries.
argument-hint: "[text-prompt or image-path]"
license: MIT
compatibility: Requires MESHY_API_KEY environment variable and internet access for Meshy AI API calls.
metadata:
  author: OpusGameLabs
  version: 1.3.0
  tags: [game, 3d, meshy, ai, model-generation, rigging, animation]

Meshy AI — 3D Model Generation, Rigging & Animation

You are an expert at generating custom 3D models with Meshy AI and integrating them into Three.js browser games. **Meshy is the preferred source for all 3D game assets** — it generates exactly what you need from a text description or reference image, with consistent art style and game-ready topology.

Performance Notes

• Take your time with each step. Quality is more important than speed.
• Do not skip validation steps — they catch issues early.
• Read the full context of each file before making changes.
• Always run post-generation verification. Never assume orientation or scale.

Reference Files

| File | Description | |------|-------------| | [api-reference.md](./api-reference.md) | Full API endpoint specs, payloads, responses, task statuses, and asset retention policy | | [rigging-pipeline.md](./rigging-pipeline.md) | Complete generate -> rig -> animate -> integrate pipeline with fadeToAction pattern and code examples | | [verification-patterns.md](./verification-patterns.md) | Auto-orientation check, auto-scale fitting, floor alignment code patterns |

Why Meshy First

• **Exact match**: Generate precisely the character, prop, or scenery your game needs — no compromises
• **Consistent style**: All assets from the same generation pipeline share a cohesive look
• **Custom characters**: Named personalities, branded characters, unique creatures — all generated to spec
• **Full pipeline**: Generate → rig → animate, all from one tool
• **Game-ready**: Control polycount, topology, and PBR textures for optimal Three.js performance

Fallback Sources

If `MESHY_API_KEY` is not available and the user declines to set one up, fall back to these in order:

| Fallback | Source | Best for | |----------|--------|----------| | `assets/3d-characters/` | Pre-built GLBs | Quick animated humanoids (Soldier, Xbot, Robot, Fox) | | `find-3d-asset.mjs` | Sketchfab, Poly Haven, Poly.pizza | Searching existing free model libraries | | Procedural geometry | Code | BoxGeometry/SphereGeometry as last resort |

Authentication

All Meshy API calls require `MESHY_API_KEY`. **Always check for this key before starting any 3D asset work.**

Before prompting the user, check if the key already exists: `test -f .env && grep -q '^MESHY_API_KEY=.' .env && echo "found"` If found, export it with `set -a; . .env; set +a` and skip the prompt.

If the key is not set in the environment or `.env`, **ask the user immediately**:

> I'll generate custom 3D models with Meshy AI for the best results. You can get a free API key in 30 seconds: > 1. Sign up at https://app.meshy.ai > 2. Go to Settings → API Keys > 3. Create a new API key > > Paste your key below like: `MESHY_API_KEY=your-key-here` > (It will be saved to .env and redacted from this conversation automatically.) > > Or type "skip" to use free model libraries instead.

If the user provides a key, use it via: `set -a; . .env; set +a && node scripts/meshy-generate.mjs ...`

If the user skips, proceed with fallback sources (character library → Sketchfab → Poly Haven).

CLI Script — `scripts/meshy-generate.mjs`

Zero-dependency Node.js script. Handles the full lifecycle: submit task → poll → download GLB → write meta.json.

Text to 3D (full pipeline)

Generates a 3D model from a text prompt. Two-step process: preview (geometry) → refine (texturing).

# Full pipeline: preview → refine → download
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a cartoon knight with sword and shield" \
  --output public/assets/models/ \
  --slug knight

# Preview only (faster, untextured — good for geometry check)
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a wooden barrel" \
  --preview-only \
  --output public/assets/models/ \
  --slug barrel

# With PBR textures and specific polycount
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a sci-fi hover bike" \
  --pbr \
  --polycount 15000 \
  --ai-model meshy-6 \
  --output public/assets/models/ \
  --slug hoverbike

Image to 3D

Turn a reference image into a 3D model. Supports URLs, local files, and base64 data URIs.

# From URL
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode image-to-3d \
  --image "https://example.com/character-concept.png" \
  --output public/assets/models/ \
  --slug character

# From local file (auto-converts to base64)
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode image-to-3d \
  --image "./concept-art/hero.png" \
  --output public/assets/models/ \
  --slug hero

Auto-Rig (humanoids only — MANDATORY for all bipedal characters)

Adds a skeleton to a generated humanoid model and **auto-downloads walking + running animation GLBs**. The input task ID comes from a completed text-to-3d or image-to-3d task.

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode rig \
  --task-id <meshy-task-id> \
  --height 1.8 \
  --output public/assets/models/ \
  --slug hero

This produces 3 files automatically:

• `hero.glb` — rigged model with skeleton
• `hero-walk.glb` — walking animation (auto-downloaded)
• `hero-run.glb` — running animation (auto-downloaded)

**Always chain generate → rig as one atomic step for humanoids.** Never leave humanoid chara