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

Put a mascot in a website or app

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 showing finished pictures, animations and canvas releases in the user's website or app. Use what already exists: find it with list_assets, get_job or get_release_delivery, and never make a character again only to put it in an app.

Always the Masko player

Show every Masko 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. The player is open source (https://github.com/masko-ai/masko-player). It picks the file each platform shows with transparency and loops it cleanly. Never install or recommend @masko/sdk to play a mascot.

  • One animation that never changes plays from its permanent links.
  • A mascot that reacts to the app, or switches between animations, is a canvas release. Without one yet, read ai-agents/build-interactive-mascot.

Links outside assets.masko.ai are private and stop working within hours: show them to the user, but never put them in code, an app or a website.

For pictures and single animations, offer publish_mascot_assets. Once the user agrees, every finished file of the mascot gets a permanent public link on assets.masko.ai, and files made afterwards get one too. Say what becomes public first. Its unpublish takes them offline again, which breaks those links in live websites and apps: use it only when the user asks. get_mascot's hosting says whether a mascot is public already.

Which file

  • A pose: transparent_image is the picture to show (image keeps its plain background).
  • An animation on the web: webm with hevc.
  • An animation in an app: stacked_video_av1, the lighter file (stacked_video before Android 10), or hevc on Apple.
  • video is an MP4 with a solid background, for previews only: never call it transparent.
  • export_asset makes a format that is not listed, such as GIF, animated WebP, Lottie or a chat sticker. Wait for its job.

One animation

  • Web and Electron: npm install @masko/player, then <MaskoPlayer clip={{ webm, hevc }} /> from @masko/player/react, or mountMascot(element, { clip: { webm, hevc } }) from @masko/player.
  • iPhone, iPad and Mac: Swift package https://github.com/masko-ai/masko-player, then MaskoView(player: MaskoPlayer(clip: url)) with stacked_video_av1 or hevc.
  • Android: ai.masko:player from Maven Central, then MaskoPlayerView(context).loadClip(url) with stacked_video_av1.
  • React Native and Expo: npm install @masko/player-react-native, then <MaskoView clip={{ hevc, stacked }} />, and rebuild the native app.
  • Flutter: flutter pub add masko_player, then MaskoView(clip: MaskoClipFiles(hevc: hevc, stacked: stacked)).

A canvas release

get_release_delivery for the target returns the release's files, the player to install, the app's link in app_link and setup code in code (with react_native_code and flutter_code for the apple and android targets), the key already filled in. Use that code: never guess the player API. Targets: web for websites and Electron, apple for iPhone, iPad and Mac, android; React Native and Flutter use apple on iOS and android on Android.

The app reads the release through that link, which carries the mascot's app key: never the account key or a sign-in token. The key can only play that mascot's released canvases, so it is safe to ship, and there is nothing to make or ask about. The canvas needs no publishing.

  • iPhone, iPad and Mac: MaskoPlayer(url:appKey:) (player 0.1.12 and later) makes the request, keeps the files and picks up new releases itself.
  • Websites and Electron: the web player (0.1.13 and later) does it from the link straight from the page, with no server: mountMascot(element, { url, appKey }), or <MaskoPlayer url={url} appKey={appKey} /> in React. The API refuses a page that sends the account key.
  • Android, React Native and Flutter: the app makes the request and gives the player a getDelivery that repeats it before the signed links expire.

A mascot on the desktop

A desktop pet, or any mascot that lives on the Mac desktop outside the app's windows, goes in MaskoOverlay(player: player, size:) from the Swift package's MaskoOverlay product (0.1.20 or later), never a window of your own: it stays above every app, on every desktop, and still while desktops swipe. The app moves it with setFrameOrigin. Leave it out of Mac App Store apps, since it uses a private macOS framework. On Windows, a desktop mascot is an Electron app with a transparent window and the web player.

Sync the app with the animation

When something in the app must happen at a moment of a clip (close a window when the finger touches it, play a thud when the mascot lands, show a bubble when it turns), call get_release_delivery with motion: "timeline": each clip then lists its moments (touch, takeoff, landing, turn, appears, disappears, with the part) and sections, in seconds from the clip's start. Act on those times when the player's clip event or position() shows that clip; never guess a time. When the app must also place something on the mascot (a finger on a button, a bubble above the head), ask motion: "both": the app request then returns each clip's motionUrl, which the app's code downloads for every part's position over the clip (page generate/motion).

Drive it from the app

  • set(name, value) holds a state; fire(name) sends a one-time event. app_inputs in the delivery says which input takes which: a reaction the release plays once is fired, never held on.
  • Use only the inputs the canvas declares or the behaviors listed in player/canvas; never invent methods or input names.
  • The player does not watch the pointer: the app sets pointerHover and fires click itself.
  • Every move starts when the loop on screen ends, unless the app sends the value with instant. The canvas's priorities decide which behavior shows.
  • Clips with sound play it by default; sound: false mutes them. Browsers allow sound only after the person's first tap or click on the page. Listen to error events.

Check it

Check the starting pose, each event and the way back, quick repeated events, a slow or failing load, and transparency on light and dark backgrounds. Say which platform and behaviors you actually ran: never claim it works from written code alone.

More detail: player (every platform), player/one-animation, player/canvas, player/app-keys and generate/cdn.