# AutoRig

> 100% local / offline auto-rigging service for humanoid 3D models. Upload a model in any common format, get a rigged + animated character back as GLB / FBX / USDZ. 635 Mixamo animations included. Designed for AI agents.

The full machine-readable API spec is at `/openapi.json`. A friendly Swagger UI is at `/docs`. An MCP (Model Context Protocol) server is mounted at `/mcp/sse` exposing 13 tools (including `autorig_build_character_pack` for iOS fighting games) — Claude Code / Cursor / Cline / Windsurf can use it directly without writing HTTP code.

## Quick API

- [Full API reference](/llms-full.txt): Complete endpoint docs with cURL + Python + MCP examples, error codes, workflow recipes
- [OpenAPI spec](/openapi.json): Machine-readable schemas with typed bodies (RigRequest, AnimRequestBody, AnimMergeBody) and enum values
- [Swagger UI](/docs): Interactive endpoint browser
- [Health check](/api/health): `GET` returns `{status, version, auth}`

## Core workflow (5 calls)

```bash
JID=$(curl -F file=@char.glb https://rig.neuralworkshk.com/api/upload | jq -r .job_id)
curl https://rig.neuralworkshk.com/api/status/$JID            # poll until status=ready
curl -X POST https://rig.neuralworkshk.com/api/rig/$JID -d '{}'
curl https://rig.neuralworkshk.com/api/status/$JID            # poll until status=done
curl https://rig.neuralworkshk.com/api/result/$JID.glb -o rigged.glb
```

Pass `?callback_url=https://your.app/done` on upload or rig to skip polling.

## MCP integration

Add to your AI client config:

```json
{"mcpServers": {"autorig": {"url": "https://rig.neuralworkshk.com/mcp/sse"}}}
```

Then call tools directly: `autorig_upload`, `autorig_rig`, `autorig_list_anims`, `autorig_export_usdz`, etc.

## Output formats

- **GLB** (`/api/result/{jid}.glb`) — glTF 2.0 binary; canonical hips orientation (identity rotation, only Y translation). Plug-and-play in Three.js / Babylon / Unity / Unreal / Blender.
- **FBX** (`/api/result/{jid}.fbx`) — ASCII FBX 7.4 with skin + bones + animations. Sidecar PNG for baseColor.
- **USDZ** (`/api/usdz/{jid}`) — for iOS RealityKit / AR Quick Look / Reality Composer Pro.
- **Character Pack ZIP** (`POST /api/character-pack/{jid}`) — single-file iOS fighting-game asset: USDZ (skeleton + skin + materials + 14 named UsdSkel.Animation clips with canonical PascalCase names) + JSON sidecar (action map + combat hitboxes + stats). Body: `{action_map, char_id?, metadata?}`. Spec-validator passes. iOS loads via `Entity.load(named:)`. See `/llms-full.txt` Character Pack section.

## Animations

- 635 Mixamo animations tagged: combat, locomotion, weapon, dance, sport, gesture, pose, zombie, magic, idle.
- Filter: `GET /api/anim-list?tag=combat&tag=punch` (AND semantics)
- Retarget on demand: `POST /api/anim/{jid}` body `{"names":["Idle","Walking"]}`, optional `?fields=duration,frame_count` to skip the 100KB+ rotation payload.

## Auth

Optional. Set `AUTORIG_API_KEY` env var on the server to require header `X-API-Key: <key>` on `/api/*`. Public routes (`/api/health`, `/api/version`, `/api/anim-list`) bypass auth. `/mcp/*` is currently always open.

## Help

If something doesn't work, GET `/api/health` first. Most issues are: jid not found (job expired after 24h), job not in `done` state yet (poll status), or non-canonical model orientation (re-rig — rigs from after 2026-05-20 have identity hips).