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

Create 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 making a mascot and its still pictures. To animate it, read ai-agents/animate-mascot; to make it react in an app, ai-agents/build-interactive-mascot; to show it in a website or app, ai-agents/integrate-mascot.

Start from what exists

get_account shows the workspace, its credit balance and the work still running. list_mascots finds a mascot by name. When the user already has the character in Masko, keep working on that mascot and its IDs; never make a replacement unless the user asks for a new one.

Make the mascot

create_mascot makes a private mascot. It draws nothing and charges nothing.

  • The user has pictures of the character: pass them in references, as asset IDs or https links. They set the look: never replace them with a description you write.
  • No pictures yet: describe it in description: what kind of creature or object it is, its shape and its colours.
  • personality holds its personality, tone and rules, such as "curious, never aggressive".
  • project files it in a project, created when no project has that name.
  • reacts_to is what in the app it reacts to, only when the user said, such as "task done, error". A mascot that reacts is a canvas: see ai-agents/build-interactive-mascot.

Pictures from the user

A picture goes in as an https link or the asset ID of a picture already in Masko. Masko cannot read files on the user's computer:

  • A coding agent on an Apple Silicon Mac uploads one with the masko command, masko studio POST upload --file <path>, which returns its asset_id.
  • When the app hands a picture the user attached to an upload tool, use the asset ID that tool returns.
  • Otherwise the user uploads it on masko.ai; find it with list_mascots and list_assets.

Never put the user's files on another public host to get a link, and never send a file path as a link.

Draw poses

generate_mascot_image draws one pose: a still picture with a transparent background, for $0.125. Tell the user the price and get a yes first, unless they already agreed.

Write pose as one still moment. It says what happens, never how the mascot looks:

  • What the body does: the posture, each arm, where the head turns and the eyes look.
  • How it feels, as the face shows it.
  • What it holds or wears, only if something.

Keep the user's intent and energy, and add nothing they did not ask for. Leave out colours, materials, art style, the background (it is removed) and the framing: the references set the look.

  • Good: "leans forward on tiptoe, both arms up in a cheer, eyes squeezed shut, huge open smile".
  • Weak: "a cute red fox in a forest, 3D style, happy".

Give every pose a name of 1 to 3 words, such as "Cheering". references with reference_note borrow a pose, expression or prop from other pictures.

Keep the look the user likes

A mascot made from a description has no reference picture, so each pose is drawn from the description alone and can differ. Show the first pose; once the user likes it, pass its asset_id to update_mascot in references, so later poses and animations match it.

Backgrounds

make_background makes an empty place in the mascot's style, with calm areas for a title and a button, for $0.375. Give its purpose (splash, paywall, a quiz result page, or your own words) and, when the user has one in mind, the place in a few words in description. place sets the shape. Never ask for the mascot, text or buttons in it.

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.

Show the result

Show the user the link from the finished job. Links outside assets.masko.ai are private and stop working within hours: show them, but never put them in code, an app or a website. For those, read ai-agents/integrate-mascot.

More detail: generate/requests (how to word every request), create/from-image and create/from-text.