3D Model Generation (Multi-Provider)

Generate 3D models from text prompts, images, or apply textures to existing models. Four providers with different cost/quality tradeoffs.

Provider Selection

Decision guide:

• Quick concept check → WaveSpeedAI ($0.02, fastest)
• Production image-to-3D → fal.ai Hunyuan3D (best PBR quality)
• Text-to-3D → Meshy (only provider with text prompt support + refine pipeline)
• Specific poly budget → Trellis 2 (--decimation 5000 for low-poly)
• Batch generation → Meshy (meshy_batch.py with manifest)
• Free offline depth/mesh → Local Depth (zero API cost, ONNX on-device)
• Depth map as preprocessing → Local Depth + any cloud provider for texturing

Prerequisites

# API key in environment (already in ~/.config/env/secrets.env)
export MESHY_API_KEY="msy_xxx"

Get your API key at: https://www.meshy.ai/settings/api

Quick Start

Test Connection

uv run ~/.claude/skills/meshy/scripts/test_meshy.py --quick

Generate a Model

uv run ~/.claude/skills/meshy/scripts/meshy_text_to_3d.py "a stealth fighter jet, delta wings" \
  --model-type lowpoly --format glb --output ./models

Check Balance

uv run ~/.claude/skills/meshy/scripts/meshy_tasks.py balance

Core Workflows

1. Text-to-3D Generation

Two-stage pipeline: Preview (geometry, ~2 min) then optional Refine (PBR textures, ~5 min).

# Full pipeline (preview + refine)
uv run ~/.claude/skills/meshy/scripts/meshy_text_to_3d.py \
  "a nuclear submarine, teardrop hull, conning tower" \
  --model-type lowpoly --filename submarine

# Preview only (saves credits)
uv run ~/.claude/skills/meshy/scripts/meshy_text_to_3d.py \
  "a red cube, game ready" --skip-refine --filename cube

2. Image-to-3D

# From local file
uv run ~/.claude/skills/meshy/scripts/meshy_image_to_3d.py ./reference.png --filename tank

# From URL
uv run ~/.claude/skills/meshy/scripts/meshy_image_to_3d.py https://example.com/photo.jpg

3. Text-to-Texture

uv run ~/.claude/skills/meshy/scripts/meshy_texture.py \
  https://cdn.meshy.ai/.../model.glb \
  --prompt "Military olive drab paint, worn metal, tactical" --enable-pbr

4. Batch Generation from Manifest

For generating multiple models (e.g., all 11 World War Watcher ordnance types):

# Generate all models from manifest
uv run ~/.claude/skills/meshy/scripts/meshy_batch.py manifest.json --output ./staging/

# Generate specific models only
uv run ~/.claude/skills/meshy/scripts/meshy_batch.py manifest.json --models fighter carrier

# Inspect manifest
uv run ~/.claude/skills/meshy/scripts/meshy_batch.py manifest.json --list
uv run ~/.claude/skills/meshy/scripts/meshy_batch.py manifest.json --dry-run

# Check status of last batch run
uv run ~/.claude/skills/meshy/scripts/meshy_batch.py manifest.json --status

5. Task Management

uv run ~/.claude/skills/meshy/scripts/meshy_tasks.py list                     # recent tasks
uv run ~/.claude/skills/meshy/scripts/meshy_tasks.py get TASK_ID              # task detail
uv run ~/.claude/skills/meshy/scripts/meshy_tasks.py get TASK_ID --watch      # poll until done
uv run ~/.claude/skills/meshy/scripts/meshy_tasks.py download TASK_ID         # download GLB
uv run ~/.claude/skills/meshy/scripts/meshy_tasks.py balance                  # credit balance

Script Reference

meshy_text_to_3d.py

meshy_image_to_3d.py

Same flags minus --negative-prompt, --skip-refine, --enable-pbr. Accepts local path (auto base64-encodes) or URL.

meshy_texture.py

meshy_tasks.py

Subcommands: list, get, download, balance. All accept --json.

meshy_batch.py

Batch Manifest Format

{
  "version": 1,
  "defaults": {
    "model_type": "lowpoly",
    "skip_refine": false,
    "format": "glb",
    "enable_pbr": true,
    "output_dir": "./output"
  },
  "models": [
    {
      "id": "fighter",
      "prompt": "a modern stealth fighter jet, delta wings...",
      "negative_prompt": "organic, blurry...",
      "output_name": "fighter.glb"
    }
  ]
}

Per-model fields override defaults. Required per-model: id, prompt.

Credit Costs

DRACO Post-Processing

For web deployment, DRACO-compress GLBs to reduce file size 80-90%:

npx gltf-pipeline -i model.glb -o model-draco.glb -d --draco.compressionLevel 7

World War Watcher's scripts/prepare-models.sh automates this for all staged models.

Troubleshooting

Alternative Providers

For full flags, API contracts, and credit costs, see the corresponding reference file:

• fal.ai Hunyuan3D → references/fal-hunyuan3d.md (credential: FAL_KEY)
• WaveSpeedAI Rapid → references/wavespeed-rapid.md (credential: WAVESPEED_API_KEY)
• Trellis 2 → references/trellis2.md (credential: THREEDAI_API_KEY)
• Local Depth → references/depth-local.md (no credential needed — free, local ONNX inference)

All three accept local file paths (auto base64-encoded) or URLs. Run any script with --help for flags.

GLB Viewer

Museum-quality standalone Three.js viewer for previewing generated .glb models. Open in browser — no server needed.

# Open with a model URL
open ~/.claude/skills/meshy/assets/glb-viewer.html?glb=https://cdn.example.com/model.glb

# Or drag-and-drop a local .glb file onto the page
open ~/.claude/skills/meshy/assets/glb-viewer.html

Features: 7-light PBR gallery rig, bloom/vignette post-processing, SMAA, auto-rotate with graceful pause, ground plane with shadow catcher.

Keyboard: D download, R toggle rotation, F fullscreen.

API Reference

See references/api-reference.md for full Meshy v2 endpoint documentation.