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
  • API keys and workspaces/docs/authentication
  • 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, scenes and stickers/docs/generate/design-assets
  • Cursor follower/docs/generate/cursor-follower
  • Batch generation/docs/generate/batch
  • 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
  • Play a mascot in your app/docs/integrations/playback
  • Hosting and file formats/docs/generate/cdn
  • File sizes/docs/generate/file-sizes
  • Image and video exports/docs/manage/media-exports
  • Terminal quickstart/docs/terminal
  • Command line reference/docs/terminal/commands
  • CLI browser login/docs/authentication/cli
  • Float a mascot on your Mac/docs/integrations/desktop
  • TypeScript SDK/docs/sdk/typescript
  • 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
  • Changelog/docs/reference/changelog
  • Migrate to mascots and canvases/docs/manage/studio-migration
Get an API key
Documentation

TypeScript SDK

Use Masko's account and canonical API from Node.js or Electron main on macOS. The SDK runs the Masko runtime for sign-in and requests. It does not display mascots.

Install

npm install @masko/sdk

@masko/sdk needs Node.js 20+ and macOS 14+. Install the runtime with the terminal setup, or bundle it with your app.

Use

import { Masko } from '@masko/sdk';

const client = Masko.client(); // Reuses your saved login.
const credits = await client.credits();
const mascots = await client.studio('GET', 'mascots');

Upgrading from 0.1.0

Version 0.2.0 removes the on-screen API: Masko.mascot, Masko.connect, Masko.playback, and the mascot methods show, state, play, position and resize. Floating mascots now run in Masko Desktop. Keep using Masko.client() for account and Studio calls, and keep API keys on your server.

Methods

CallResult
Masko.client({ apiURL?, apiKey?, runtimePath? })Creates a client. An apiKey stays in memory.
client.login({ noBrowser?, device?, apiKey? })Signs in with a browser or device code, or validates and saves an API key.
client.logout()Revokes the saved session.
client.whoami()Returns the current account and session.
client.credits()Returns the credit balance: total, subscription and top-up.
client.studio(method, path, body?)Calls a canonical v1 path with GET, POST, PATCH or DELETE.
client.assets.show(id)Returns one asset.
client.assets.download(id, { output })Downloads one asset to output.

studio() paths are relative to /v1 and must start with mascots, canvases, projects, jobs, assets or upload. Other paths are rejected before any request is sent. Use the migration guide for current route names.

Keys and errors

Use this SDK on a server, or in trusted tooling. Never put an API key in a shipped app or a public repository. The SDK sends an in-memory key to the runtime over stdin, never as a command argument.

Errors are MaskoError objects with code, message and optional details. Account and studio calls need the macOS runtime, so call them from Electron main or Node.js, never from a browser page or renderer.

Next steps

Read the quickstart for the REST calls behind these operations, and the authentication guide for API keys and workspaces.