# Animate API

Animations for a rigged humanoid, whoever rigged it (an auto-rig job, Mixamo, Blender, a game's own rig), all in one GLB, in place, each by name, after any it has. animation-library (free): up to 20 of 79 animations by id, from Quaternius' CC0 Universal Animation Library: walks, jogs, sprints, jumps, rolls, sitting, talking, punches, sword and shield moves, pistols, spells, farm work. hunyuan-motion (credits): one motion described in words, up to 12 s. Humanoids only.

Tool id `animate` on the REST API (`POST https://3dvalley.com/api/v1/jobs`); MCP tool `animate_model` on https://3dvalley.com/mcp. Paid in credits (1 credit = $0.01), taken when the job starts and given back if it fails. The general rules (keys, idempotency, waiting, webhooks) are in [the API docs](https://3dvalley.com/docs/api).

The library's animations are searchable by words: `GET /api/v1/assets?type=animation&q=sword` (MCP: `search_assets` with `type: "animation"`); each result's `animate_id` goes in `options.animations`.

## Models and prices

| Model | Name | Price | Time | What it is |
|---|---|---|---|---|
| `animation-library` (default) | Animation library | 0 credits | about 3 s | 79 ready-made animations by Quaternius, free: walks, jogs, jumps, rolls, sitting, punches, sword combos, spells, farming and more, put on your rig. |
| `hunyuan-motion` | Hunyuan Motion | 15 credits | about 30 s | Any motion you describe, made by Tencent's Hunyuan Motion and put on your rigged humanoid. |

## Input

| Field | Required | |
|---|---|---|
| `mesh` | yes | A mesh (GLB, glTF, OBJ, PLY or STL) as an https URL, an upload id (upl_...), a library id (ph:wooden_barrel_01) or an earlier job (job_... or its asset id 3dv:...). A rigged humanoid: an auto-rig job (job_...) or any GLB with a humanoid skeleton. |
| `prompt` | no | hunyuan-motion: one person moving, in a sentence, in English: "waves hello with the right hand, then sits down cross-legged". No animals, props or a second person. Up to 400 characters. |

## Options

| Option | Type | Values | |
|---|---|---|---|
| `animations` | list | `walk`, `walk-formal`, `jog`, `sprint`, `crouch-walk`, `carry-walk`, `zombie-walk`, `jump-start`, `jump-air`, `jump-land`, `ninja-jump-start`, `ninja-jump-air`, `ninja-jump-land`, `roll`, `slide-start`, `slide`, `slide-end`, `climb`, `swim`, `tread-water`, `push`, `drive`, `idle`, `talk`, `phone`, `arms-folded`, `yes`, `no`, `torch`, `lantern`, `rail`, `rail-call`, `crouch`, `sit-down`, `sitting`, `sitting-talk`, `stand-up`, `get-up`, `dance`, `zombie-idle`, `jab`, `cross`, `hook`, `sword-idle`, `sword-attack`, `sword-slash-1`, `sword-slash-2`, `sword-slash-3`, `sword-combo`, `sword-heavy-combo`, `sword-dash`, `sword-block`, `shield-up`, `shield-bash`, `shield-charge`, `shield-broken`, `hit-chest`, `hit-head`, `knockback`, `death`, `zombie-scratch`, `pistol-idle`, `pistol-aim`, `pistol-shoot`, `pistol-reload`, `throw`, `spell-start`, `spell-hold`, `spell-cast`, `spell-end`, `interact`, `pick-up`, `open-chest`, `eat`, `repair`, `chop-tree`, `plant`, `water`, `harvest` | animation-library: the animations to add, by id, in the order given. walk (Walk), walk-formal (Formal walk), jog (Jog), sprint (Sprint), crouch-walk (Crouch walk), carry-walk (Carry), zombie-walk (Zombie walk), jump-start (Jump), jump-air (In the air), jump-land (Land), ninja-jump-start (Ninja jump), ninja-jump-air (Ninja jump, in the air), ninja-jump-land (Ninja jump, landing), roll (Roll), slide-start (Slide), slide (Sliding), slide-end (Slide, getting up), climb (Climb up a ledge), swim (Swim), tread-water (Tread water), push (Push), drive (Drive), idle (Idle), talk (Talk), phone (Talk on the phone), arms-folded (Arms folded), yes (Nod yes), no (Shake head no), torch (Hold a torch), lantern (Hold a lantern), rail (Lean on a rail), rail-call (Call out from a rail), crouch (Crouch), sit-down (Sit down), sitting (Sitting), sitting-talk (Talk, sitting), stand-up (Stand up), get-up (Get up from the ground), dance (Dance), zombie-idle (Zombie idle), jab (Jab), cross (Cross punch), hook (Hook), sword-idle (Sword ready), sword-attack (Sword attack), sword-slash-1 (Sword slash 1), sword-slash-2 (Sword slash 2), sword-slash-3 (Sword slash 3), sword-combo (Sword combo), sword-heavy-combo (Heavy sword combo), sword-dash (Sword dash), sword-block (Sword block), shield-up (Shield up), shield-bash (Shield bash), shield-charge (Shield charge), shield-broken (Shield broken), hit-chest (Hit in the chest), hit-head (Hit in the head), knockback (Knocked back), death (Die), zombie-scratch (Zombie scratch), pistol-idle (Hold a pistol), pistol-aim (Aim a pistol), pistol-shoot (Shoot a pistol), pistol-reload (Reload a pistol), throw (Throw), spell-start (Raise a spell), spell-hold (Hold a spell), spell-cast (Cast a spell), spell-end (Lower a spell), interact (Interact), pick-up (Pick up from a table), open-chest (Open a chest), eat (Eat or drink), repair (Repair, kneeling), chop-tree (Chop a tree), plant (Plant seeds), water (Water plants), harvest (Harvest). |
| `seconds` | number | from 1 to 12 | hunyuan-motion: how long the motion lasts, in seconds. Default `5`. |
| `seed` | integer | from 0 to 2147483647 | Fixes the randomness, so the same input makes the same result. |

## Output

Files: `glb`. `glb` is the rig with the new animations after the ones it had, each named after its animation ("Walk", "Sword combo", or the first words of a motion), in place: the hips rise and sink but stay over the spot, and the game moves the character. An animation-library job costs 0 credits; send its glb (or its job id) to another animate job to add more.

## Example

```
curl -X POST https://3dvalley.com/api/v1/jobs \
  -H "Authorization: Bearer $THREEDVALLEY_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=50" \
  -H "Content-Type: application/json" \
  -d '{"tool":"animate","model":"animation-library","input":{"mesh":"job_9Kp4..."},"options":{"animations":["idle","walk","jog","jump-start"]}}'
```

From an MCP client:

```
animate_model({"mesh":"job_9Kp4...","animations":["idle","walk","jog","jump-start"]})
```

## Limits

- `max_image_bytes`: 10,485,760
- `max_mesh_bytes`: 62,914,560
- `max_animations`: 20
- `max_prompt`: 400