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

Batch generation and AI suggestions

Queue up to 10 generations in one call, and get free pose ideas for your mascot.

Batch Generation

Each entry in requests uses the same fields as /generate, except speech, and all run in parallel. The call returns 202 Accepted with the queued jobs.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate-batch \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "type": "image",
        "name": "Waving",
        "image_prompt": "waving hello with a friendly smile"
      },
      {
        "type": "image",
        "name": "Thinking",
        "image_prompt": "hand on chin, looking up thoughtfully"
      },
      {
        "type": "animation",
        "name": "Celebrating",
        "image_prompt": "jumping with arms raised in celebration",
        "animation_prompt": "0.00-0.90s: crouches, wriggling with excitement. 0.90-2.00s: jumps up with both arms high as confetti bursts around it. 2.00-3.10s: lands and bounces, confetti drifting down. 3.10-4.20s: jumps again, arms still high. 4.20-5.17s: lands and crouches into the next jump.",
        "animation_model": "standard",
        "duration": 5,
        "loop": true
      }
    ]
  }'

When to Batch vs Sequential

Batch when you know every item up front, such as a full pose set for a new mascot. Send requests one by one when a generation needs an earlier result, such as animating a new image with source_image_asset_id after its job completes.

AI Pose Ideas

Get pose ideas written for your mascot from its references and personality, the same ideas Studio offers, for free. Each idea has a name, a pose for the still picture and an animation with the matching motion. suggestions lists the names, as before.

curl "https://api.masko.ai/v1/mascots/MASCOT_ID/suggestions?count=3" \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

Send an idea's name as name and its pose as image_prompt in a batch, and its animation as animation_prompt with type: "animation".

  • count sets how many ideas, 1 to 15 (default 8).
  • The ideas are saved on the mascot and returned again without being written anew, so reading them twice gives the same list. Pass refresh=true for new ones. Ideas saved by an older idea writer are written again once, for free, on the next read.
  • A read-only key never replaces current saved ideas: with it, refresh=true returns new ideas without saving them.
  • variant_id writes ideas for an approved variant. These are always new and not saved.
  • Ideas whose name the mascot already has as an item are left out, so you can call it again as the pose library grows.
  • Writing new ideas counts toward a daily limit of 300 free ideas per account, shared with background ideas, voice ideas, voice rewrites and talking dry runs. Past it, the call returns 429 with code rate_limited. Returning saved ideas does not count.

Partial acceptance

A batch is not atomic: the outer 202 does not mean every request was accepted. Check each entry in data.jobs for a real job_id, poll accepted jobs individually, and review missing entries before retrying. Never resend the whole batch after an uncertain response.