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

Build an interactive 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. 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. The Masko player plays a release of the canvas in the app and runs all its rules.

The steps

  1. Make the mascot and one finished picture of it (ai-agents/create-mascot). Reuse what exists: get_mascot lists a mascot's canvases.
  2. create_canvas with its graph: the poses, each pose's loop, the moves between poses and the inputs the app sets. To change a canvas, read it with get_canvas and save the whole graph with save_canvas and the expected_graph_hash you read.
  3. estimate_canvas_generation prices what is missing. Tell the user the price and get a yes.
  4. generate_canvas with the estimate's plan_id, the max_credits the user agreed to and an operation_id.
  5. When every clip is ready, release_canvas makes a playable release and returns the app's link for each platform.
  6. get_release_delivery returns its files, the player to install, the app's link and the code that plays it, ready to paste. Then read ai-agents/integrate-mascot.

The graph

  • Nodes are poses: assetId for a finished picture, or imagePrompt for a still moment to draw ($0.125). A label alone draws nothing.
  • Edges are animations. An edge from a node to itself is that pose's animation, and the first one without conditions is its loop. An edge between two nodes is a transition, played when its conditions on inputs hold; priority decides between them (highest wins).
  • Any State: an edge with source * fires from any node and needs duration 0.
  • Reverse edges (reverse true with reverseOfEdgeId) play another edge backwards for free; never point one at its forward video.
  • Inputs: the app holds a behavior such as behavior::celebrate with set(name, true), and sends one-off events with fire('<event>') to action::<event>. initialNode is the start.

Build what the user asked: a sensible starting pose, the actions, their conditions and a way back. Never add a large default graph or behaviors nobody asked for.

Keep node and edge IDs when you save. Masko keeps the media of unchanged poses and animations; a changed prompt, duration or pose drops that clip, and the next generation makes it again. To reuse a clip the mascot already has, set videoAssetId to one the estimate lists under reusable (free). On a stale hash, read the canvas again and merge the changes instead of overwriting them.

Write each clip

An edge's description is one action, with how big, how fast and the mood, never the mascot's look. A loop keeps the action going and never lowers, returns or settles at its end. Each clip is made at its edge's own duration (whole seconds, Standard 2 to 15) when set, else at the estimate's.

Masko times each clip from its pictures when it is generated. When the user wants to see or change how the clips will move before paying, call save_canvas with improve set to true (the graph can be left out): it writes each unmade clip's improved, timed prompt into the canvas and returns them, free. Each is one range per line, to the hundredth of a second, from 0.00 to the clip's real length, which its seconds gives, as in ai-agents/animate-mascot. Show the user each clip's motion and save their changes to its text, keeping the ranges one after another from 0.00 to that end; then estimate and generate, and Masko keeps those ranges.

Validation

create_canvas, get_canvas and save_canvas return the validation. valid means the graph is sound. clips_to_generate and pictures_to_generate count what generating will make; they are not errors to fix. Fix an invalid graph before generating.

Estimate and generate

  • Check the estimate's planned_nodes, planned_edges and cost_credits_usd against what the user asked before asking to spend.
  • Pass the estimate's plan_id to generate_canvas with the agreed max_credits. A later round of work needs a fresh estimate and a fresh yes.
  • Never edit the graph while its generation runs. Follow the run with get_job, then read get_canvas until its media is ready.
  • generate_canvas also repairs missing playback files of existing clips, for free: never make a clip again to fix a file.

Release and ship

  • release_canvas needs the current graph hash and an operation_id. A release is not a marketplace listing and does not change a mascot in Masko for Mac.
  • get_release_delivery takes the target: web for websites and Electron, apple for iPhone, iPad and Mac, android; React Native and Flutter use apple on iOS and android on Android. desktop is only for Masko for Mac. Use its code field: never guess the player API. Its app_inputs say which inputs to set and which to fire.
  • The app's link comes with the release: it reads the canvas's newest release with the mascot's app key inside, and the code get_release_delivery returns already holds that key. Give the app that link, never the account key. There is nothing to make or ask about: the key can only play this mascot's released canvases, so it is safe in the app. The user sees its use in App keys on the mascot's page in Studio.
  • A canvas needs no publishing.

Jobs, retries and failures

  • get_job waits up to 40 seconds per call; call it again until the run is completed or failed. Never start the same work again while it runs; 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.
  • Failed clips give back their credits; get_canvas lists which, and a new estimate retries them.
  • 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.

More detail: canvas/build (every graph field), canvas/generate-all, player/canvas (inputs and behaviors) and player/app-keys.