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] }
]
}
}
}| Field | What it is |
|---|---|
timeline.sections | The 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.moments | Instants 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.facing | left, right or viewer, over the whole clip with no gap. Mirror the mascot from it. |
parts.whole | The 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[].t | Seconds from the start of the clip. A track keeps only the moments where something changes; fill in between them. |
track[].state | visible, 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[].open | Eyes and mouths: 0 closed to 1 wide open. |
track[].look | Eyes: 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.
