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

Animate a mascot

This guide is for an AI agent working with Masko's MCP tools; read_docs reads the other guides and docs pages it names. It covers single animations, sound, a voice and talking animations. A mascot that reacts to an app or website, is interactive, or changes between animations is a canvas, never separate animations switched by code you write: read ai-agents/build-interactive-mascot for that. To show an animation in a website or app, read ai-agents/integrate-mascot.

Find the picture

An animation starts from a finished pose. Find the user's mascot with list_mascots and its poses with list_assets, or use the picture the user gives as an https link. Never make a replacement character when the user asks to animate their own. Without a usable picture, ask for one, or draw a pose first (ai-agents/create-mascot).

animate_mascot takes the picture as source: a pose's asset_id or an https link. It finds the mascot from the picture, or takes mascot_id; a new picture becomes a new mascot in the named project. A picture that is not square is cut to its centred square unless crop gives the square to keep.

Write the motion

motion is plain words, or the timed prompt Masko returned (see below). In plain words it is one action, continued or repeated: what happens, how big, how fast and the mood, kept to what the user asked, never how the mascot looks.

  • Good: "bounces on the spot with excitement, quick and springy, arms flung up at each jump".
  • Weak: "moves nicely, then returns to the start pose".

In a loop the motion keeps going into the next cycle: it never lowers, returns or settles at the end, because Masko joins the end to the start. For an action that ends somewhere else, such as falling asleep, set loop to false. Give every clip a name of 1 to 3 words, such as "Wave hello".

See and edit Masko's timed prompt

Masko times the motion from the picture into ranges, to the hundredth of a second, that cover the clip's real length (Standard's real length is a little off the seconds asked, 5 s as 5.17 s and 4 s as 3.75 s). You never work it out: the seconds that improve returns is the exact length to end the last range on. For a 5-second wave, improve returns a motion such as:

0.00-1.10 s: lifts its right paw high, quick and bright, eyes widening.
1.10-2.60 s: waves the paw side to side twice, wide and bouncy, a big open smile.
2.60-3.90 s: leans a little toward the viewer, waving faster with excitement.
3.90-5.17 s: keeps waving, paw still high, swinging into the next wave.
  1. Unless the user already said to go ahead, call animate_mascot with improve set to true. It is free and makes nothing: it returns that timed motion, the seconds it covers and the price.
  2. Show the user the text and the price, and apply their changes to it: change the words of a range, move a boundary, or split a range for a new moment ("add a wink at the end"). Keep the ranges one after another from 0.00 to the seconds it returned, with no gap.
  3. Call animate_mascot again without improve, with that edited text as motion. Masko keeps those ranges as the plan and only fine-tunes them. A last range ending at the seconds asked (5.00) is moved to the real end; ranges that do not cover the whole clip are timed again, keeping their order and emphasis.

When the user already said to go ahead, make it in one call with plain words: Masko times it the same way.

Price

Standard costs $0.25 a second, from 2 to 15 whole seconds; 5 seconds when duration is left out. Tell the user the price and get a yes before making it. Never raise the duration or make more clips than asked without saying so.

Sound

Set sound to true when the user wants the animation heard (Standard, 5 to 15 seconds, same price). Masko uses one of the mascot's own sounds (get_mascot lists them) when one fits or the motion names it ("says yippee"), timed to the motion; otherwise it makes a sound for it. No sound picked is not a failure. To add one of the user's sounds, pass its https audio link to update_mascot as add_sound.

Redos and where it plays

  • When the user found an animation wrong and wants it made again, pass its asset ID in replaces and what was wrong in redo_reason.
  • When the user said where it plays, put it in used_for, such as "onboarding welcome, greets new users". Leave it out otherwise, and never put the motion there.

A voice

sample_mascot_voices records three voices from one description, all reading the same line, for $0.125. Describe gender (or gender-neutral), pitch, pace, energy, texture, mood and accent in one or two sentences, such as "gender-neutral, light, bright and slightly raspy, quick and warm, with a playful American accent". Never a child's age: say light, bright or small instead. Without a description it charges nothing and returns voice ideas, each with a line in the mascot's words for the samples.

Once the user picks a sample, update_mascot with voice_sample_id keeps it as the mascot's voice, within 24 hours. It replaces the old voice for good.

Talking animations

make_talking_animation makes the mascot say a line in its voice while it moves: a video with sound, an MP3 and a timed transcript. It needs a voice and a pose to start from, and costs $0.25 a second of speech.

  • text is the words to say. Pass the user's words exactly; when you write them, keep to one to three short sentences (3 to 10 seconds). Masko adds the movements without changing a word, and direction, such as "proud, points at the button at the end", steers them.
  • Write a script only when the user dictates movements: [2 to 6 words for what its own body does where it stands, optional feeling after a comma] before the words, such as "[waves, excited] Hi, I'm Pika!". No props, no walking, nothing toward or away from the viewer.
  • max_credits is the most the user agreed to spend. Above it, the tool charges nothing and returns the price.

Jobs, retries and failures

  • Every paid call returns a job. get_job waits up to 40 seconds per call for its result; call it again until the job is completed or failed. Never start the same work again while its job is running; after an interruption, get_account lists the work still running.
  • operation_id makes a call safe to retry: the same ID returns the first answer and never charges twice. After a timeout, retry with the same ID and the same inputs.
  • A failed job gives back the credits for what it did not make. To try again, ask the user and use a new operation_id: the old one returns the failed job.
  • When something looks like a Masko problem, offer to tell the Masko team with send_feedback, quoting the tool, the error and its request_id.

Prices and credits

Say prices and balances in dollars, from the fields ending in _usd. Inputs such as max_credits stay in credits, at $0.125 each. When credits run short, stop paid work and tell the user what the work costs and what the workspace has. No tool takes a payment.

The files

A finished animation lists its files by format in get_job and list_assets (video is an MP4 with a solid background, for previews only); export_asset makes GIF, Lottie or a chat sticker. Show every animation with the Masko player, even a single loop: never a video tag, motion added to a still picture or playback code of your own, unless the user asks for another way. Links outside assets.masko.ai are private and stop working within hours. ai-agents/integrate-mascot says which file each platform plays, the player setup and how to get permanent links.

More detail: generate/requests (how to word every request), generate/animations, generate/sounds and generate/talking.