// Sync request
{
  "prompt": "Create a smooth walk cycle for a humanoid character",
  "engine": "unity"
}

// Sync response
{
  "generation_id": "gen_abc123",
  "engine": "unity",
  "animation_type": "skeletal",
  "files": [
    {
      "filename": "WalkCycleController.cs",
      "language": "csharp",
      "content": "using UnityEngine;\npublic class WalkCycleController : MonoBehaviour { ... }"
    }
  ],
  "preview_data": { "format": "threejs_compatible", "scene": { ... } },
  "metadata": {
    "tokens_input": 312,
    "tokens_output": 748,
    "generation_time_ms": 2340,
    "model": "claude-3-5-sonnet-20241022"
  }
}

// Async request
{
  "prompt": "Create an explosion particle system",
  "engine": "unity",
  "async": true,
  "webhook_url": "https://your-app.com/webhooks/mcpity"
}

// Async response (immediate)
{
  "generation_id": "gen_xyz789",
  "status": "pending",
  "message": "Generation queued. Poll /status or wait for webhook."
}

// Request
{
  "generation_id": "gen_abc123",
  "refinement_prompt": "Make the arm swing wider and add a subtle head bob"
}

// Response: same shape as /generate, plus:
{
  "generation_id": "gen_def456",
  "parent_generation_id": "gen_abc123",
  "engine": "unity",
  "files": [ ... ]
}

// GET ?action=templates&engine=unity&category=character

{
  "templates": [
    {
      "id": "walk-cycle-unity",
      "name": "Humanoid Walk Cycle",
      "description": "Smooth locomotion animation for Unity Animator",
      "engines": ["unity"],
      "animation_type": "skeletal",
      "category": "character",
      "difficulty": "beginner",
      "tags": ["locomotion", "humanoid", "animator"],
      "prompt_template": "Create a walk cycle animation for a {character_type} character ...",
      "parameters": [
        { "key": "character_type", "label": "Character Type", "default": "humanoid", "description": "Type of character rig" }
      ]
    }
  ],
  "count": 1,
  "filters": { "engine": "unity", "category": "character", "animation_type": null }
}

// Response
{
  "preview_data": {
    "format": "threejs_compatible",
    "version": "1.0",
    "engine": "unity",
    "animation_type": "transform",
    "scene": {
      "objects": [ { "type": "mesh", "geometry": "BoxGeometry", ... } ],
      "animations": [ { "name": "walk", "duration": 1.0, "tracks": [ ... ] } ],
      "camera": { "position": [0, 2, 5], "target": [0, 1, 0] }
    }
  },
  "format": "threejs_compatible"
}

// Pending
{ "generation_id": "gen_xyz789", "status": "pending", "engine": "unity" }

// Generating
{ "generation_id": "gen_xyz789", "status": "generating", "engine": "unity" }

// Completed
{
  "generation_id": "gen_xyz789",
  "status": "completed",
  "engine": "unity",
  "completed_at": "2025-03-01T12:00:05Z",
  "files": [ ... ],
  "preview_data": { ... },
  "metadata": { ... }
}

// Failed
{
  "generation_id": "gen_xyz789",
  "status": "failed",
  "error_message": "Claude API error: rate limit exceeded"
}