Character Animation for Agents

Give this to your agent

Read https://townbox-character-animation-for-agents.hf.space/llms.txt and use this service to <WHAT_TO_RIG_OR_ANIMATE_AND_WHAT_TO_DO_WITH_THE_FILES>. Use my configured Hugging Face token if available.

Connect over MCP

{
  "mcpServers": {
    "character-animation": {
      "url": "https://townbox-character-animation-for-agents.hf.space/gradio_api/mcp/",
      "headers": { "Authorization": "Bearer <HF_TOKEN>" }
    }
  }
}

First call: animate_mesh with a model URL (or an example id) and a prompt that starts with “An object”; the result carries the rig, the asset and the motion with every file URL. Its asset id is reusable in animate and expand, its animation job id is the reference for inbetween and edit_joints. Signed in on the Hub, the Space's Agents menu also adds it to your Hugging Face MCP tools.

How the pieces fit

POST /api/animate_mesh (MCP animate_mesh) runs all three in one request and returns a p_ result with the three stages and a flat map of file URLs; rig_job_id or asset in its body skip the stages already done. Results are kept 24 h, assets until the Space restarts.

Examples generated by this Space

6 real outputs of this API, produced on 2026-11-05 on the ZeroGPU slice: 4 by POST /api/animate_mesh (each model rigged by SkinTokens, prepared as an asset, animated by UniMate, in one request), then one /api/expand chain and one /api/edit on those assets. Each picture is an animated GIF of the generated motion, rendered from the animation GLB the API returned (15 fps, camera fixed on the whole path); click it to load the 3D mesh itself (drag to orbit). Under each: the rig preview the API returns (mesh with the predicted skeleton) and the asset preview (what the motion model is told: canonical T-pose, facing pair, labels), or the skeleton motion itself for the expansion and the edit. The seeds reproduce them; the API always generates fresh results. Machine-readable list: /api/examples.

“An object walks forward.”

Giraffe, textured quadruped, 14.8k vertices → POST /api/animate_mesh: SkinTokens rig of 47 joints (15.8 s GPU, 10 beams, seed 7, textures kept) · asset prepared in 5.8 s (facing Right Thigh / Left Thigh, 0 flagged) · UniMate motion seed 7, 6.8 s GPU · root travel 0.78 · 34 s in all

animation.glb · joints.json · motion.npy · skeleton.mp4 · contact sheet · rigged.glb · rig.json · rest.glb · jobs p_474f884eebc5 (rig r_2e6699f3f0bc, asset u_10e5b2e20af3, motion a_2f76391d6eda)

“An object walks forward.”

Cesium Man, humanoid, 3.3k vertices (Khronos sample, rig removed) → POST /api/animate_mesh: SkinTokens rig of 19 joints (5.5 s GPU, 10 beams, seed 7) · asset prepared in 3.1 s (facing Right Thigh / Left Thigh, 0 flagged) · UniMate motion seed 7, 8.2 s GPU · root travel 0.05 · 20 s in all

animation.glb · joints.json · motion.npy · skeleton.mp4 · contact sheet · rigged.glb · rig.json · rest.glb · jobs p_2f231730c8f6 (rig r_7f2aec849775, asset u_953687e8544d, motion a_046e8815e9d9)

“An object runs forward.”

Fox, low-poly, 1.7k vertices (Khronos sample, rig removed) → POST /api/animate_mesh: SkinTokens rig of 22 joints (6.5 s GPU, 10 beams, seed 7) · asset prepared in 2.7 s (facing Right Thigh / Left Thigh, 0 flagged) · UniMate motion seed 5, 7.5 s GPU · root travel 1.33 · 20 s in all

animation.glb · joints.json · motion.npy · skeleton.mp4 · contact sheet · rigged.glb · rig.json · rest.glb · jobs p_86e991769686 (rig r_50d711b04d7f, asset u_2e9a5e883e0a, motion a_7b7af3060632)

“An object jumps in place.”

Low-poly humanoid, 370 vertices (Khronos sample, rig removed) → POST /api/animate_mesh: SkinTokens rig of 19 joints (5.5 s GPU, 10 beams, seed 7) · asset prepared in 2.8 s (facing Right Thigh / Left Thigh, 0 flagged) · UniMate motion seed 3, 6.8 s GPU · root travel 0.07 · 25 s in all

animation.glb · joints.json · motion.npy · skeleton.mp4 · contact sheet · rigged.glb · rig.json · rest.glb · jobs p_2f7fbbcc7328 (rig r_b90ee872d15b, asset u_f3fd9ef728c3, motion a_4baf1f28fa50)

Expansion: “An object walks forward.” → “An object turns around.” → “An object sits down.” (160 frames, 5.3 s)

Giraffe, textured quadruped, 14.8k vertices, the asset of example 01 → POST /api/expand, 3 prompts, overlap 10 · seed 7 · 12.2 s GPU · root travel 1.00 · segments at frames 0, 50, 100

animation.glb · joints.json · motion.npy · skeleton.mp4 · contact sheet · job a_7d5d52020ca4

Joint editing: “An object waves its arms.” with the legs of the walk kept

Cesium Man, humanoid, 3.3k vertices (Khronos sample, rig removed), the walk of example 02 as reference → POST /api/edit, keep_joints = Left Foot, Left Shin, Left Thigh, Left Toe, Right Foot, Right Shin, Right Thigh, Right Toe (8 joints) · seed 4 · 5.6 s GPU · 11 joints regenerated

animation.glb · joints.json · motion.npy · skeleton.mp4 · contact sheet · job a_c861220fef36

Bundled example assets

Meshes: the example ids of POST /api/rig and /api/animate_mesh. Each link opens the file in the Hugging Face file viewer (3D preview, history, download from there) rather than downloading it.

Skeletons: prepared assets, the asset ids of POST /api/animate and /api/expand; they need no rigging.

For programs: /api/examples lists the same inputs with a mesh_url per mesh, and GET /api/assets/{id}/rest.glb serves a skeleton’s canonical GLB. The folders on the Hub: examples/ (also holds the showcase outputs above) and assets/examples/ (with each skeleton’s annotation.json, cond.npy and preview).

Quick start

BASE=https://townbox-character-animation-for-agents.hf.space
# one call: mesh -> rig -> asset -> animated GLB (about a minute; GPU time goes to your ZeroGPU quota)
curl -s -X POST $BASE/api/animate_mesh -H "Authorization: Bearer $HF_TOKEN" -H 'content-type: application/json' \
  -d '{"example": "giraffe", "prompt": "An object walks forward.", "seed": 7}'
# your own model: the file as the body, the prompt as a query parameter
curl -s -X POST "$BASE/api/animate_mesh?filename=robot.glb&prompt=An%20object%20walks%20forward." \
  -H "Authorization: Bearer $HF_TOKEN" -H 'content-type: application/octet-stream' --data-binary @robot.glb
# download the animated, rigged mesh (urls.animation_glb of the result)
curl -s -H "Authorization: Bearer $HF_TOKEN" -o walk.glb "$BASE/api/jobs/<a_job_id>/files/sample0_animation.glb"

# the stages, one call each
curl -s -X POST $BASE/api/rig -H "Authorization: Bearer $HF_TOKEN" -H 'content-type: application/json' -d '{"example": "fox", "seed": 7}'
curl -s -X POST $BASE/api/assets -H "Authorization: Bearer $HF_TOKEN" -H 'content-type: application/json' -d '{"rig_job_id": "<r_job_id>"}'
curl -s -X POST $BASE/api/animate -H "Authorization: Bearer $HF_TOKEN" -H 'content-type: application/json' \
  -d '{"asset": "<u_asset_id>", "prompt": "An object jumps in place.", "num_samples": 2}'
# keep what you like, regenerate the rest (reference = an a_ job), or chain prompts
curl -s -X POST $BASE/api/edit -H "Authorization: Bearer $HF_TOKEN" -H 'content-type: application/json' \
  -d '{"reference_job_id": "<a_job_id>", "keep_joints": "Left Thigh, Right Thigh, Left Shin, Right Shin", "prompt": "An object waves its arms."}'
curl -s -X POST $BASE/api/expand -H "Authorization: Bearer $HF_TOKEN" -H 'content-type: application/json' \
  -d '{"asset": "<u_asset_id>", "prompts": ["An object walks forward.", "An object turns around.", "An object sits down."]}'

Endpoints

Parameters

Outputs

Models and provenance

Skin Tokens: A Learned Compact Representation for Unified Autoregressive Rigging. Jia-peng Zhang, Cheng-Feng Pu, Meng-Hao Guo, Yan-Pei Cao, Shi-Min Hu. ACM Transactions on Graphics 2026. arXiv 2602.04805 · code (MIT) · weights (MIT) · authors' Space. This service runs the released checkpoint grpo_1400.ckpt (TokenRig, 595M parameters) through the authors' own inference code, vendored from their Space at revision 1f4445ba; Blender 4.5 reads the input and writes the rigged GLB. The same engine as SkinTokens for Agents.

UniMate: One Unified Model to Animate Diverse Skeletons. Linzhan Mou, Jiahui Lei, Zhiyang Dou, Chenyue Cai, Chaoyue Song, Adam Finkelstein, Szymon Rusinkiewicz. SIGGRAPH Asia 2026. arXiv 2609.05415 · project page · code (MIT) · checkpoints (CC BY-NC 4.0). This service runs unimate_uniml3d_f60_v3 step 150000 (EMA weights, 74M-parameter flow-matching transformer, 50 ODE steps) with the frozen google/flan-t5-base text encoder through the repository's own inference code at commit b78c7807, and prepares assets with the repository's own data_process.rig_preprocess pipeline (offline rule annotation, no LLM). The same engine as UniMate for Agents. The animated GLB comes from a Blender-free glTF baker checked against Blender's importer (1e-5).

SkinTokens code and weights are MIT; UniMate code is MIT and its weights are for non-commercial research use (CC BY-NC 4.0; the training data keep their own terms). The bundled example assets keep their licenses (listed above and by /api/examples). The UniMate project page's 3D showcase is access-controlled and is not used; every output of this service is generated live. Details in PROVENANCE.md.

Limitations

SkinTokens names joints bone_i, builds a single-rooted tree, occasionally stops early (the service retries once with the next seed) and gives arbitrary skeletons to shapes that are not characters. The labels of such a rig come from the rest-pose geometry (symmetry, limbs, floor, trunk, head, tail), so unusual bodies or a lying / upside-down rest pose get placeholder labels or no facing pair: the asset preview and the flags show it, labels, face_right / face_left and rest_rotation correct it; at most 71 joints. UniMate has no contact model (feet can slide or hover), rare skeletons and motions can come out static, jittery or off-prompt, and it generates 60 frames per prompt (longer through expansion) as rotations only. Ask for several samples, try a few phrasings, raise cfg_scale to 5 to 7 when a prompt is ignored.