Skip to content
maskostudioDocs

All pages

  • Overview/docs/use-cases
  • Mobile app/docs/use-cases#mobile
  • Website/docs/use-cases#website
  • Desktop/docs/use-cases#desktop
  • AI agents/docs/use-cases#agents
  • Videos/docs/use-cases#videos
  • Brand/docs/use-cases#brand
  • Start building/docs/ai-agents
  • Set up once/docs/ai-agents#set-up-once
  • Ask in plain words/docs/ai-agents#ask-in-plain-words
  • What your agent does/docs/ai-agents#what-your-agent-does
  • MCP server/docs/mcp
  • Agent guide: create a mascot/docs/ai-agents/create-mascot
  • Agent guide: animate a mascot/docs/ai-agents/animate-mascot
  • Agent guide: interactive mascot/docs/ai-agents/build-interactive-mascot
  • Agent guide: website or app/docs/ai-agents/integrate-mascot
  • Masko for Cursor/docs/ai-tools/cursor
  • Masko in ChatGPT/docs/ai-tools/chatgpt
  • Masko in Lovable/docs/ai-tools/lovable
  • Masko in Devin/docs/ai-tools/devin
  • Masko in n8n/docs/ai-tools/n8n
  • Masko in Hermes Agent/docs/ai-tools/hermes
  • Masko in OpenClaw/docs/ai-tools/openclaw
  • Start here/docs/tutorials#start-here
  • All tutorials/docs/tutorials
  • Create your first mascot/docs/tutorials/first-mascot
  • Create an animated character/docs/tutorials/first-animation
  • Make a character talk/docs/tutorials/make-it-talk
  • Put your mascot on your website/docs/tutorials/mascot-on-your-website
  • Guide onboarding with a talking mascot/docs/tutorials/web-onboarding-mascot
  • Add a mascot that celebrates progress and welcomes users back/docs/tutorials/web-progress-companion
  • Add a talking support mascot in the bottom right/docs/tutorials/web-support-mascot
  • Show a mascot while your AI thinks/docs/tutorials/ai-loading-mascot
  • Give your AI agent a face/docs/tutorials/ai-agent-face
  • Animate the mascot you already have/docs/tutorials/animate-your-mascot
  • How to make Telegram stickers/docs/tutorials/telegram-stickers
  • How to make Discord stickers/docs/tutorials/discord-stickers
  • Quickstart: your first animation/docs/quickstart
  • Terminal quickstart/docs/terminal
  • API keys and workspaces/docs/authentication
  • CLI browser login/docs/authentication/cli
  • How mascots work/docs/how-mascots-work
  • Credits and costs/docs/credits
  • From text/docs/create/from-text
  • From an image/docs/create/from-image
  • From a website/docs/create/from-website
  • From a brand book/docs/create/from-brand-book
  • Reference images/docs/manage/references
  • Props/docs/manage/props
  • What you can generate/docs/generation
  • Pose-to-animation walkthrough/docs/generate/workflow
  • Images and poses/docs/generate/images
  • Animations/docs/generate/animations
  • Talking animations/docs/generate/talking
  • Sounds/docs/generate/sounds
  • Motion/docs/generate/motion
  • Animation presets/docs/generate/presets
  • Write good requests/docs/generate/requests
  • Logos, backgrounds and stickers/docs/generate/design-assets
  • Cursor follower/docs/generate/cursor-follower
  • Batch generation/docs/generate/batch
  • Image and video exports/docs/manage/media-exports
  • Canvases and releases/docs/canvas
  • Build a canvas/docs/canvas/build
  • Canvas templates/docs/canvas/templates
  • Generate canvas assets/docs/canvas/generate-all
  • Export a canvas/docs/canvas/export
  • Overview and demo/docs/player
  • Play one animation/docs/player/one-animation
  • Play a canvas/docs/player/canvas
  • Ship in an app with an app key/docs/player/app-keys
  • Play on an ESP32 board/docs/player/esp32
  • Hosting and file formats/docs/generate/cdn
  • File sizes/docs/generate/file-sizes
  • Float a mascot on your Mac/docs/integrations/desktop
  • Jobs and polling/docs/manage/jobs
  • Webhooks/docs/manage/webhooks
  • Manage mascots and assets/docs/manage/collections
  • All endpoints/docs/reference
  • Requests and responses/docs/reference/conventions
  • Errors and recovery/docs/reference/errors
  • Command line reference/docs/terminal/commands
  • TypeScript SDK/docs/sdk/typescript
  • Changelog/docs/reference/changelog
  • Migrate to mascots and canvases/docs/manage/studio-migration
Get an API key
Documentation

Motion

Every animation Masko makes is read for its motion, about a minute after it is ready. You get two things, with times:

  • What happens and when: the stretches of the clip, the instants to act on (a hand touches, the mascot takes off or lands, turns, a prop appears) and which way the mascot faces.
  • Where everything is: a box and a point for the whole mascot and for each of its parts (hands, feet, eyes, mouth, tail, wings, whatever this mascot has), plus the props and icons of the clip, over the whole clip.

Use it to move a desktop pet as its feet move, to close a panel at the instant the mascot's finger lands on it, to keep a speech bubble next to its head while it jumps, or to make the same move on another mascot from its timeline. It is read from the video itself and changes nothing about the animation. It costs nothing.

Get it for one animation

Ask for the animation's video with include=motion. The answer is the asset, with motion added.

curl "https://api.masko.ai/v1/assets/VIDEO_ID?include=motion" \
  -H "Authorization: Bearer $MASKO_API_KEY"

include=motion.timeline returns only the timeline, which is a few hundred bytes; include=motion adds every part's track, 20 to 120 KB. Without include, the asset is returned as always. motion is null while the video is not analysed yet; the video's metadata.motion.status says ready when it is, or failed.

Get it for a canvas

Add include to a canvas delivery. With include=motion.timeline, each clip whose video has been analysed carries motionTimeline, its sections, moments and facing, inside the answer: a few hundred bytes a clip. With include=motion, it carries motionUrl, a signed link to its whole motion, next to its video links. Send both as include=motion,motion.timeline. Without include, the delivery is unchanged.

Over MCP, get_release_delivery takes motion: timeline lists each clip's moments and sections, links adds include=motion to the app's own request, and both does both.

curl "https://api.masko.ai/v1/canvases/CANVAS_ID/delivery?target=web&include=motion,motion.timeline" \
  -H "Authorization: Bearer $MASKO_API_KEY"

It is read from the clips as they are now, so a canvas released before its clips were analysed has it too.

What it contains

{
  "version": 1,
  "duration": 3.04,
  "timeline": {
    "sections": [
      { "start": 0, "end": 0.7, "what": "Faces the viewer, holding the cup to its mouth with both hands." },
      { "start": 0.7, "end": 1.75, "what": "Turns right, lowers the cup and raises a thumb." },
      { "start": 1.75, "end": 3.04, "what": "Stretches its arm out and points far to the right, then holds." }
    ],
    "moments": [
      { "t": 0.54, "name": "turn", "part": "body" },
      { "t": 2.04, "name": "touch", "part": "hand_right" }
    ],
    "facing": [
      { "start": 0, "end": 0.54, "facing": "viewer" },
      { "start": 0.54, "end": 3.04, "facing": "right" }
    ]
  },
  "parts": {
    "whole": { "role": "whole", "track": [{ "t": 0, "state": "visible", "box": [0.29, 0.16, 0.66, 0.91] }] },
    "hand_right": {
      "role": "points",
      "track": [
        { "t": 1.83, "state": "visible", "point": [0.57, 0.56], "box": [0.55, 0.55, 0.6, 0.61] },
        { "t": 2.04, "state": "visible", "point": [0.81, 0.43], "box": [0.71, 0.42, 0.81, 0.51] }
      ]
    }
  }
}
FieldWhat it is
timeline.sectionsThe stretches of the clip, one after the other, each with start, end (seconds) and what. Written so the move can be made again on another mascot.
timeline.momentsInstants to act on: touch (a hand or finger at its furthest reach), takeoff, landing, turn (the whole body faces another way), appears and disappears (a prop or icon). part names the part when there is one.
timeline.facingleft, right or viewer, over the whole clip with no gap. Mirror the mascot from it.
parts.wholeThe box around the whole mascot: the area to click or grab, how much room it takes, and its bottom is where it stands.
parts.<name>One of the mascot's parts, or a prop or icon of this clip. role is touches_ground, points, held_prop, eyes, mouth, wing, body, other, prop or effect.
track[].tSeconds from the start of the clip. A track keeps only the moments where something changes; fill in between them.
track[].statevisible, hidden (there but covered, such as a mouth behind noodles) or absent (not in the picture; it then has no position).
track[].point, track[].box[x, y] and [left, top, right, bottom], from 0 to 1 across the picture, (0, 0) being its top-left corner. The point is a part's useful spot: the tip of the fingers, the middle of a sole.
track[].openEyes and mouths: 0 closed to 1 wide open.
track[].lookEyes: where the face looks, viewer, left, right, up, down or closed.

Names. Each mascot has its own parts, only what it really has, and keeps the same names in all its clips. _left and _right mean the side of the picture. Props and icons belong to their clip, and their names are not matched across clips: find them by their role.

Position on screen. Positions are shares of the clip's picture. On a mascot drawn 170 points wide, a point at [0.81, 0.43] is 138 points from its left edge and 73 from its top.

Examples

A desktop pet that presses a button. Read the clip's touch moment and hand_right at that time, and move the window so that point lands on the button. Act at t.

A speech bubble that follows the head. While a clip plays, read the head or eyes at the player's time (position() gives the clip on screen and its time) and draw the bubble above it.

The same move on another mascot. Send the sections as the timed description of a new animation for the other mascot: its own body makes the move at the same times.

Animations made before November 2026 are not analysed.