Meshyai

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

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:

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 characters as static models.

Limitations: Rigging works only on textured humanoid (bipedal) models with clearly defined limbs. Won't work on animals, vehicles, abstract shapes, or untextured meshes.

Animate

Apply an animation to a rigged model. Requires a completed rig task ID and an animation action ID.

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

Check Status

Poll any task's current status.

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode status \
  --task-id <task-id> \
  --task-type text-to-3d   # or: image-to-3d, rigging, animations

Non-blocking Mode

Submit a task without waiting. Useful in pipelines.

MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d \
  --prompt "a crystal sword" \
  --no-poll

# Later:
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode status --task-id <id> --task-type text-to-3d

Automatic GLB Optimization

All downloaded GLBs are automatically optimized via scripts/optimize-glb.mjs to reduce file sizes by 80–95%. The pipeline resizes textures to 1024×1024, converts them to WebP, and applies meshopt compression.

• Optimization runs by default after every GLB download (text-to-3d, image-to-3d, rig, animate)
• Use --no-optimize to skip optimization and keep the raw Meshy output
• Use --texture-size <n> to change the max texture dimension (default: 1024)
• First run may take a moment as npx downloads @gltf-transform/cli
• If gltf-transform is unavailable, the script warns and continues with the raw file

Optimized GLBs use meshopt compression and require MeshoptDecoder at runtime — the template AssetLoader.js includes this automatically.

# Skip optimization for a specific generation
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d --prompt "a barrel" --preview-only \
  --no-optimize --output public/assets/models/ --slug barrel

# Custom texture size (e.g., 512 for mobile)
MESHY_API_KEY=<key> node scripts/meshy-generate.mjs \
  --mode text-to-3d --prompt "a barrel" --preview-only \
  --texture-size 512 --output public/assets/models/ --slug barrel

# Re-optimize an existing GLB directly
node scripts/optimize-glb.mjs public/assets/models/barrel.glb --texture-size 512

API Reference

See api-reference.md for full endpoint specs, payloads, responses, task statuses, and asset retention policy.

Quick Reference: Static Props (no rig needed)