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

TypeScript SDK

Call the Masko API from Node.js or Electron main on macOS. The SDK runs the masko command for sign-in and requests, so it uses your saved login. It does not display mascots.

Install

npm install @masko/sdk

@masko/sdk 0.3.0 needs Node.js 20+, an Apple Silicon Mac with macOS 14+, and the masko command 0.4.0 or later. Install it with the terminal setup, or bundle it with your app. With an older command, calls fail with sdk_update_required and the install command to run.

Use

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

const client = Masko.client({ client: 'my-app/1.0' }); // Reuses your saved login.
const credits = await client.credits();
const { data: mascots, meta } = await client.studio('GET', 'mascots?limit=50');
const job = await client.studio('POST', 'mascots/MASCOT_ID/generate', {
  type: 'animation',
  item_id: 'ITEM_ID',
  animation_model: 'standard', // 2 credits a second
  animation_prompt: 'waves hello'
});

Methods

CallResult
Masko.client({ apiURL?, apiKey?, runtimePath?, client? })Creates a client. An apiKey stays in memory. client names your app to Masko.
client.login({ noBrowser?, device?, apiKey? })Signs in with a browser or device code, or validates and saves an API key.
client.logout()Signs out on this Mac and revokes the saved session.
client.whoami()Returns the account, workspace name, access and credits.
client.credits()Returns the credit balance: total, subscription and top-up.
client.studio(method, path, body?, { idempotencyKey? })Calls a Masko API path with GET, POST, PUT, PATCH or DELETE. Returns { data, meta? }.
client.feedback(text)Sends feedback to the Masko team. The first line is the summary.
client.assets.show(id)Returns one asset.
client.assets.download(id, { output })Saves one asset as the new file output, in a folder that exists. It never overwrites a file.

studio() takes the API's /v1 paths, such as mascots, jobs/JOB_ID?wait=true or credit-checkouts; a job's poll_url works too. Sign-in, admin and the old collections paths are rejected before any request is sent. It returns the API's response: data, plus meta.pagination for lists, where next_cursor gets the next page. See the API reference.

Every POST sends an idempotency key. To retry a failed POST without running or charging it twice, pass the key from its error as idempotencyKey.

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 the API's details (for example required and available credits). When the API answered they also carry status, requestId, docUrl and param; a failed POST carries its idempotencyKey. Account and API calls need the macOS runtime, so call them from Electron main or Node.js, never from a browser page or renderer.

Upgrading

  • From 0.2.0: studio() returns { data, meta } instead of data alone, so read .data. Assets and jobs use mascot_id instead of collection_id. Update the masko command to 0.4.0 at the same time.
  • From 0.1.0: version 0.2.0 removed the on-screen API (Masko.mascot, Masko.connect, Masko.playback, and show, state, play, position, resize). Floating mascots run in Masko for Mac.

Next steps

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