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

Terminal quickstart

The masko command signs in to your Masko account and calls the Masko API for you: the same requests and responses as the REST API, with your browser login instead of an API key. It runs on Apple Silicon Macs with macOS 14 or later. It does not show mascots on screen; Masko for Mac does, see Float a mascot on your Mac.

Coding agents such as Claude Code, Codex and Cursor can also connect to the Masko MCP server, which needs no install.

Install

curl -fsSL https://releases.masko.ai/cli/install.sh | sh

This installs the signed, notarized CLI at ~/.local/bin/masko, adds that folder to your PATH in ~/.zshrc (or ~/.bash_profile for bash), and opens your browser to sign you in. Over SSH it shows a code to enter on any device instead, and Ctrl+C skips sign-in. Then open a new terminal before you run masko. Running the installer again updates the CLI and keeps your sign-in; in scripts and CI it never waits for a browser. To leave your shell profile alone, put MASKO_NO_MODIFY_PATH=1 on the right side of the pipe and add export PATH="$HOME/.local/bin:$PATH" yourself. No Xcode, Node.js or checkout is needed. Intel Macs, Linux and Windows can use the REST API or the MCP server.

The installer sends anonymous install reports, never account data. To turn them off, put the variable on the right side of the pipe:

curl -fsSL https://releases.masko.ai/cli/install.sh | MASKO_TELEMETRY_DISABLED=1 sh

That choice is kept for later installs. DO_NOT_TRACK=1 works too. The masko command itself sends no analytics.

Sign in and check your account

masko login
masko whoami
masko credits

The installer already signed you in. masko login signs in again, for example to switch account or workspace: it prints a link, opens your browser and returns after you approve; choose your account and workspace there. Over SSH or on another computer, use masko login --device --no-browser. See CLI login. masko logout signs out on this Mac.

Make a mascot

masko studio METHOD PATH calls any Masko API path. --file sends a JSON body, or an image or video to upload.

masko studio GET projects
masko studio POST upload --file character.png
masko studio POST mascots --file mascot.json
masko studio POST mascots/MASCOT_ID/generate --file pose.json
masko studio GET 'jobs/JOB_ID?wait=true'
masko assets download ASSET_ID --output mascot.webm

mascot.json can be {"project_id": "PROJECT_ID", "name": "Ko", "reference_asset_ids": ["ASSET_ID"]}, with a project from the first command and the asset_id that upload returned. pose.json can be {"type": "image", "name": "Wave", "prompt": "waving hello"}, or {"type": "animation", "item_id": "ITEM_ID", "animation_model": "standard", "animation_prompt": "waves hello"} to animate a pose. The quickstart lists every field. Generation spends credits: an image is 1 credit and a Standard animation 2 credits a second. Name the model: without animation_model, the older price of 5 credits a second applies. A mascot made from a prompt draws its first image for 1 credit and is hosted on the public CDN unless settings.cdn_enabled is false.

The output is the API's own response: data, plus meta.pagination for lists. When has_more is true, ask for the next page with next_cursor:

masko studio GET 'assets?mascot_id=MASCOT_ID&limit=100'
masko studio GET 'assets?mascot_id=MASCOT_ID&limit=100&cursor=NEXT_CURSOR'

Paths are the API's /v1 paths, such as mascots, canvases/CANVAS_ID or credit-checkouts; a job's poll_url works as it is. Sign-in, admin and the old collections paths are not available here. Requests use API version 2026-09-26, like the MCP server.

Retry without paying twice

Every POST sends an idempotency key. When a POST fails without an answer, or you press Control+C, masko prints its key. Run the same command with that key, and Masko returns the first result instead of running or charging it again:

masko studio POST mascots/MASCOT_ID/generate --file pose.json --idempotency-key KEY

Errors

Errors print the API's code and message, the field that was wrong and a request ID to give support. With --json they are JSON on stdout, {"error": {"code", "message", "status", "request_id", "doc_url", ...}}, and the exit code is 1. A 402 says how many credits are needed and where to buy more, on Billing. See errors.

Update or choose a version

Run the install command again for the latest version; your sign-in is kept. Once a day, masko also says when a newer version is out (MASKO_NO_UPDATE_CHECK=1 turns that off). To install a specific version, use its number from the changelog:

curl -fsSL https://releases.masko.ai/cli/install.sh | MASKO_VERSION=0.4.0 sh
masko --version

Next steps