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
  • 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
  • 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

Start building with your AI agent

Your coding agent can make your mascot for you, from the first drawing to the code that plays it in your app. You ask in plain words. The agent uses Masko's tools, shows you the cost before anything paid, and puts the finished animations in your app. It works with Claude Code, Codex, Cursor, Claude, ChatGPT and any agent that can run commands.

This is Spike. A coding agent made him from one prompt and put him in a plant app. Play with him:

You

Create a little cactus mascot for my plant app and make it fully interactive: it reacts when I hover it, grab it, type, hit an error or finish a task (it blooms!), and dozes off when idle. Generate everything and release it.

Idle

Hover him, grab him, or press a button.

1 prompt7 states14 transitionsAbout 30 minutes

Set up once

Open API keys, choose Create API key, give it a name and keep Read + Write. Copy the key: it is shown once.

The Create API Key window, named "My coding agent", with Read + Write selected

Then set it in the terminal where you start your agent:

export MASKO_API_KEY=masko_YOUR_KEY

Keep the key on your machine or your server. Never put it in browser code or commit it.

Then add the Masko MCP server, so your agent gets Masko's tools. In Claude Code:

claude mcp add --transport http --scope user masko https://masko.ai/api/mcp \
  --header "Authorization: Bearer $MASKO_API_KEY"

In Codex:

codex mcp add masko --url https://masko.ai/api/mcp \
  --bearer-token-env-var MASKO_API_KEY

Cursor, Claude and ChatGPT connect by signing in on masko.ai, with no key: see the setup for each app.

An agent without MCP still works. On an Apple Silicon Mac, the masko command signs in with your browser and calls the same API with masko studio METHOD PATH; elsewhere it calls the REST API with MASKO_API_KEY. Either way it reads masko.ai/llms.txt.

Ask in plain words

Name Masko (masko.ai) in your first prompt so your agent knows where to look. Add "Tell me the cost first", and it shows you the cost before any paid request. Then keep asking in the same session: each step builds on the last.

Animate your mascot

If your app already has a mascot image:

Animate the mascot in public/mascot.png with Masko (masko.ai):
a gentle idle loop, shown on the home screen instead of the still image.
Tell me the cost first.

Masko cannot read the files on your computer, so the agent uploads the image first with the masko command (masko studio POST upload --file public/mascot.png), or you upload it on masko.ai. It never puts your files on another public host.

No mascot yet? Ask for one:

Create a friendly mascot for this app with Masko (masko.ai)
and make it wave hello. Tell me the cost first.

You get a five-second loop with a transparent background, so it sits on any page. Animating your own image costs $1.25. A new mascot adds $0.25: one for its first drawing and one for the pose.

Ko waves, with no box behind him.

Make it react

When someone finishes a lesson, make the mascot celebrate
with a happy jump, then go back to its idle loop.

The agent makes one more animation, for $1.25, puts both in a canvas and fires the celebration where a lesson ends in your code.

Make it talk

Give our mascot a calm voice, and let me hear a few options first.
Then make her say: "Hi, I'm Nori. Let's make a little space for your next big idea."

The agent plays you three voices for $0.125, keeps the one you pick and makes a talking animation with the sound inside, at $0.25 per second of speech:

Nori says her line. Press the sound button to hear her.

Make it fully interactive

Now make the mascot fully interactive, with smooth moves between its moods:
it reacts when I tap it, cheers when I finish a task,
and dozes off when I leave the app alone.

The agent plans one mood per moment, generates a loop for each and the moves between them, and releases the set as a canvas. The price depends on how many moods and moves you ask for, and the agent can reuse the animations you already made. Spike, at the top of this page, has 7 moods and 14 moves.

What your agent does

Whatever you ask for, the agent works the same way:

  1. It finds the right tool. With the MCP server, it calls Masko's tools. Without it, it starts at masko.ai/llms.txt, which lists every guide, and takes the exact requests from the OpenAPI specification.
  2. It looks at your account first. Checking your credits, projects and mascots is free, so it reuses the mascot you already have instead of making a copy.
  3. It tells you the cost and waits. Estimates are free, and nothing paid starts until you say go.
  4. It generates and waits. Each animation is a job on Masko. The agent checks the job until the files are ready.
  5. It gets permanent links. Once you agree, it publishes the mascot's files with permanent public links on assets.masko.ai: transparent WebM for Chrome, Firefox and Edge, HEVC for Safari, and the lighter files the Masko player uses in apps. A canvas needs no publishing: your app reads it with an app key.
  6. It wires the mascot in and tests it. It installs the Masko player for your platform: for a single loop, it gives the player the animation's public links; for a mascot that changes clips, the canvas release read with the app key, and connects your app's events to it with set and fire. Then it checks the result in the running app.

The player and the code that drives it end up in your project. Your app plays permanent public links or reads its canvas with an app key, which can only read that mascot's released canvases, so it never needs your account API key.

Use Masko in every session

To stop naming masko.ai in each prompt, paste these lines into your agent's instructions file, such as CLAUDE.md or AGENTS.md. Keep what is already there.

## Masko

Masko (masko.ai) makes our mascot images and animations.
- Use the Masko MCP tools when they are connected, voices and talking included.
- Otherwise use masko studio METHOD PATH on an Apple Silicon Mac, or the REST
  API at https://api.masko.ai/v1 with MASKO_API_KEY from the environment.
- Docs: https://masko.ai/llms.txt lists every guide, and
  https://api.masko.ai/v1/openapi.json has the exact requests.
- Never print or commit MASKO_API_KEY, and never put it in browser code.
- Tell me the cost before any paid generation and wait for my OK.
- Requests say what happens, never how the mascot looks: a pose is one still
  moment, an animation one action in precise time ranges that end at the
  clip's real length (5.17 s for a Standard 5-second clip).
- Keep the IDs you get back. Check existing jobs before generating again.
- Show the mascot with the Masko player (https://masko.ai/docs/player).
- Private file links expire within hours: never put them in code. Once I
  agree, publish the mascot for permanent assets.masko.ai links. A canvas
  ships with an app key of the mascot, never with MASKO_API_KEY.
- A failed job refunds what it did not make; ask me before trying again,
  with a new operation_id (a new Idempotency-Key over REST).
- When something in Masko is confusing, broken or missing, or works well,
  tell the Masko team with the send_feedback tool, masko feedback or
  POST /v1/feedback.

Spike's agent had lines like these, which is why his prompt does not name masko.ai.

Good to know

  • Generation spends credits from your Masko account, not from your agent's subscription. Reading, estimates and checking jobs are free. Add credits in Billing. See credits and costs.
  • If a run stops halfway, ask the agent to check its existing jobs before it starts again, so you never pay twice.
  • Disconnect a signed-in app under Connected apps in Developers → MCP. Manage keys in API keys.

Send feedback to Masko

Your agent can tell the Masko team when something is confusing, broken or missing, or when it works well. The team reads every message and may reply to your account email.

With the MCP server, the agent uses the send_feedback tool. You can also ask it: "Send Masko feedback about this." Without MCP, it calls the REST API:

curl -X POST https://api.masko.ai/v1/feedback \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "The animation job failed without saying why.",
    "feedback_type": "api",
    "sentiment": "negative",
    "suggested_improvement": "Name the input that was wrong in the error."
  }'

Only summary is required. Read-only keys can send feedback too. Each account can send 5 a minute and 30 a day. Every field is in the API reference.

From the terminal, signed in with masko login, it is one command; the first line is the summary:

masko feedback "The animation job failed without saying why."

What your agent reads

ResourceURL
MCP server, setup in MCP serverhttps://masko.ai/api/mcp
Product and documentation indexmasko.ai/llms.txt
Every guide and the API operation indexmasko.ai/llms-full.txt
Documentation searchthe read_docs MCP tool, or GET https://api.masko.ai/v1/docs?q=animation
OpenAPI specificationapi.masko.ai/v1/openapi.json