Animation Converter API

# Animation Converter API

> **BETA**: This tool is currently being tested. Please report any issues.

Convert Mixamo or Unreal animations to s&box Citizen skeleton format. Remaps bone names so animations work with s&box's built-in Citizen/Human models.

## Endpoint

```
POST /api/tools/animation
```

## Parameters

Send as `multipart/form-data`.

| Field | Required | Description |
|---|---|---|
| `file` | Yes | FBX animation file. Max 100MB. |
| `preset` | No | Bone mapping preset: `mixamo` (default), `unreal`, or `custom` |
| `mapping` | Only for `custom` preset | JSON object with bone name mappings: `{"sourceBone": "targetBone", ...}` |

## Response

```json
{
  "ok": true,
  "downloadUrl": "/uploads/temp/123/animation_citizen_1714400000.fbx",
  "preset": "mixamo",
  "bonesRenamed": 22,
  "channelsRenamed": 156,
  "animations": [
    {
      "name": "mixamo.com",
      "frames": 60,
      "start": 0,
      "end": 60
    }
  ],
  "logs": [
    "Using preset: mixamo (65 bone mappings)",
    "Found 1 armature(s)",
    "Renamed 22 bones, 156 animation channels",
    "Animation 'mixamo.com': 60 frames (0-60)"
  ]
}
```

## Bone Mapping Presets

### Mixamo (default)

Maps standard Mixamo rig bones to Citizen skeleton:

| Mixamo | Citizen |
|---|---|
| `mixamorig:Hips` | `pelvis` |
| `mixamorig:Spine` | `spine_0` |
| `mixamorig:Spine1` | `spine_1` |
| `mixamorig:Spine2` | `spine_2` |
| `mixamorig:Neck` | `neck_0` |
| `mixamorig:Head` | `head` |
| `mixamorig:LeftArm` | `arm_upper_L` |
| `mixamorig:LeftForeArm` | `arm_lower_L` |
| `mixamorig:LeftHand` | `hand_L` |
| ... | (65 total mappings) |

### Unreal

Maps Unreal Mannequin bones to Citizen skeleton:

| Unreal | Citizen |
|---|---|
| `pelvis` | `pelvis` |
| `spine_01` | `spine_0` |
| `spine_02` | `spine_1` |
| `upperarm_l` | `arm_upper_L` |
| `lowerarm_l` | `arm_lower_L` |
| ... | (similar structure) |

## Workflow

1. Download animation from Mixamo (FBX format, "Without Skin")
2. Upload to this endpoint with `preset=mixamo`
3. Download converted FBX from the `downloadUrl`
4. In s&box ModelDoc, create a new VMDL that extends `citizen.vmdl`
5. Add the converted FBX as an animation sequence

## Example: cURL

```bash
# Convert Mixamo animation
curl -X POST https://api.sboxcool.com/tools/animation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "preset=mixamo"

# Download the converted FBX
curl -o walking_citizen.fbx https://sboxcool.com/uploads/temp/123/animation_citizen_xxx.fbx
```

## Example: Python

```python
import requests

resp = requests.post("https://api.sboxcool.com/tools/animation",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    files={"file": open("Running.fbx", "rb")},
    data={"preset": "mixamo"})

data = resp.json()
print(f"Renamed {data['bonesRenamed']} bones")

fbx = requests.get(f"https://sboxcool.com{data['downloadUrl']}")
with open("running_citizen.fbx", "wb") as f:
    f.write(fbx.content)
```

## Example: Custom Mapping

```bash
curl -X POST https://api.sboxcool.com/tools/animation \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@custom_rig_anim.fbx" \
  -F "preset=custom" \
  -F "mapping={\"MyHips\":\"pelvis\",\"MySpine\":\"spine_0\",\"MyChest\":\"spine_2\"}"
```

## Adding to s&box

After converting, create an animation-only VMDL in s&box ModelDoc:

1. File > New > Model
2. Add a "BaseModel" node pointing to `citizen.vmdl`
3. Add an "AnimFile" node pointing to your converted FBX
4. The animation will now work with Citizen's animgraph