Animate a 3D model

Send a rigged humanoid GLB (one skeleton with two legs, two arms and a head) and a description of a motion. The motion is generated for a standard human body and transferred onto your skeleton: bone roles are found from the skeleton's shape, the character's own facing and proportions are kept, and feet that touch the ground are kept planted and on the floor. The file comes back unchanged except for one added animation, 1 to 10 seconds at 30 frames per second; earlier animations are replaced. motion.json lists the bone roles, facing, travel and foot contacts; motion_report.json gives the status (passed, needs_review or failed_checks) and each issue with its frames; motion_preview.png shows six moments from the front and the side. A succeeded job means the motion was written, not that it looks right. Start the job, keep its id and poll: it takes a few minutes.

Formats

.glb with one skeleton: two legs, two arms and a head (a rig from Rig a 3D model, or from any other tool)

Outputs

model.glb (the same model with one animation), motion.json, motion_report.json, motion_preview.png and generation.json

Motion

1 to 10 seconds at 30 frames per second, travelling or in place

Checks

Planted feet sliding or floating, the model going through the floor, sudden bone turns

Duration

Asynchronous; one-hour deadline including queueing and execution

Send the file as the request body with the options in the query string, or refer to it in a JSON body (upload_id or url) with an options object. The response is the new job; poll it until its status is final, then download the files in result.files.

# idempotency_key is required: repeating it returns the same job
curl https://api.mcpbytes.com/v1/tools/animate_3d_model/jobs \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_file": {"job_id": "j_...", "name": "model.glb"},
    "options": {
      "description": "A person walks forward confidently.",
      "duration": 5,
      "seed": 42
    },
    "idempotency_key": "animate-example-001"
  }'

{
  "tool": "animate_3d_model",
  "status": "queued",
  "input_kind": "file",
  "workflow": {
    "stage": "Animating",
    "deadline": "2026-09-27T23:21:27.662Z",
    "cancel_pending": false,
    "refund_pending": false
  },
  "capabilities": {
    "can_cancel": true
  },
  "options": {
    "description": "A person walks forward confidently.",
    "duration": 5,
    "in_place": false,
    "seed": 42
  },
  "result": null
}

# JOB_ID is the id from the create response; poll until status is final
curl "https://api.mcpbytes.com/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY"

# Once status is succeeded, download each file from result.files[].url
curl -fsSLo model.glb "$MODEL_URL"

{
  "tool": "animate_3d_model",
  "status": "succeeded",
  "result": {
    "notes": [],
    "duration": 5,
    "frames": 150,
    "status": "passed",
    "issues": [],
    "files": [
      {
        "name": "model.glb",
        "bytes": 15060048,
        "content_type": "model/gltf-binary",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "motion.json",
        "bytes": 3168,
        "content_type": "application/json",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "motion_report.json",
        "bytes": 580,
        "content_type": "application/json",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "motion_preview.png",
        "bytes": 252926,
        "content_type": "image/png",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "generation.json",
        "bytes": 2323,
        "content_type": "application/json",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      }
    ]
  },
  "compute_ms": 27551,
  "credits_charged": 20
}

Jobs of this tool take minutes. While one runs, workflow.stage says what is happening and workflow.deadline when it must finish. Cancel it with POST /v1/jobs/{id}/cancel while capabilities.can_cancel is true.

More on statuses, downloads and retention in Jobs & files.

One file per job, in one of these ways. The formats it accepts are listed in the overview.

# 1. Create an upload URL (valid for one hour)
curl https://api.mcpbytes.com/v1/uploads \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "model.glb"}'

# 2. PUT the file to the "url" from the response
curl -X PUT --data-binary @model.glb "$UPLOAD_URL"

# 3. Start the job with the "upload_id"
curl https://api.mcpbytes.com/v1/tools/animate_3d_model/jobs \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"upload_id\": \"$UPLOAD_ID\",
    \"options\": {
      \"description\": \"A person walks forward confidently.\",
      \"duration\": 5
    },
    \"idempotency_key\": \"animate_3d_model-upload-001\"
  }"

Put options in the query string when the file is the request body, in the options object of a JSON body, or pass them as arguments of the MCP tool. Leave an option out to use its default.

A succeeded job lists its files in result.files, each with a download url.

Download links last up to 24 hours, capped by output retention; read the job again for fresh links. A succeeded job means the motion was written; whether it looks right is in motion_report.json and motion_preview.png.

Result summary

Next to files, the job's result has a summary you can check without downloading anything:

• Describe the motion as "A person…" with one or two actions: "A person walks forward confidently", "A person waves with their right hand". Everyday movement, gestures, dancing and fighting work best.
• Send the description in the JSON body or as MCP arguments, never in a URL.
• Pass model.glb of a rig_3d_model job as job_file. A model rigged elsewhere works too, as long as its skeleton has two legs, two arms and a head.
• Read motion_report.json and look at motion_preview.png before using the clip. If it fails its checks, try another seed or wording; each job is charged.
• in_place keeps the character on the spot, for a clip your engine moves itself; otherwise it travels as it walks or runs.
• Motions on the ground (sitting, kneeling) can push a tail or long clothes through the floor; the report says so.

Your agent calls animate_3d_model. Connect it to https://api.mcpbytes.com/mcp/3d for this tool and the rest of its family (Create a 3D model, Create a 3D model from an image, Optimize a 3D model, Simplify a 3D model, Rig a 3D model, Split a 3D model into parts, Inspect a 3D model), or to https://api.mcpbytes.com/mcp for every tool.

claude mcp add --transport http mcpbytes \
  https://api.mcpbytes.com/mcp/3d

codex mcp add mcpbytes --url https://api.mcpbytes.com/mcp/3d \
  --bearer-token-env-var MCPBYTES_API_KEY

{
  "mcpServers": {
    "mcpbytes": {
      "url": "https://api.mcpbytes.com/mcp/3d",
      "headers": {
        "Authorization": "Bearer ${env:MCPBYTES_API_KEY}"
      }
    }
  }
}

Arguments

The tool's options are flat arguments. Besides them:

What the agent sees

Setup for every client, and how agents upload files and read results: Connect over MCP.

The MCPBytes skill teaches agents this tool, in references/animate_3d_model.md. Agents without MCP run it through the REST API with the skill's script, which reads your key from MCPBYTES_API_KEY:

printf '{"description": "A person waves with their right hand.",
  "duration": 4}' > options.json
python scripts/mcpbytes.py run animate_3d_model \
  --job-file j_... model.glb \
  --options-json options.json --out animated/

20 credits per job. The price is charged before paid processing starts, and a canceled job is refunded. A job that fails costs nothing: its charge is refunded.

One credit balance pays for every tool, and a new account starts with free credits. See Credits & prices or buy credits.

GET /v1/me returns your limits and current usage; Limits & errors explains what happens when one is reached.

A failed job comes back with error.code, error.message and often error.hint. Codes are stable. Inputs that fail with a validation error will fail again unchanged.

Requests can also fail before a job starts, with an HTTP status: see HTTP errors.

• Rig a 3D modelIts model.glb goes straight in as job_file.rig_3d_model
• Create a 3D modelCreate the character, then rig it: the rigged model.glb is this tool's input.create_3d_model
• Create a 3D model from an imageBuild the character from a picture, then rig it before animating.create_3d_model_from_image