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

Reference images and style consistency

Keep a mascot on-model in every pose with persistent reference images and a style card. Several fields accept images, each for a different purpose.

URL imports, including reference URLs:

  • Public HTTP(S) images up to 10 MB, downloaded within 15 seconds.
  • Every redirect must resolve to a public address. Private addresses and URLs with credentials are rejected.
  • PNG, JPEG, WebP, GIF and SVG (converted to PNG).

Which image field to use

WherePersistenceUse case
POST /v1/mascots/:id/references (body: asset_id or url)PersistentStyle anchors for every generation in this mascot. Max 6.
reference_image_urls / reference_asset_ids on POST /v1/mascotsPersistent (seeded at creation)Same as above, set when creating the mascot. An image that already belongs to another mascot is copied: that mascot keeps it.
PreviewBody.reference_image_urls on /v1/generate/previewEphemeral (one-off)Style hints for a single preview, not stored.
visual_references on image generation or image editingOne requestUp to 4 pose, expression, motion, prop, style, or scene hints, each with asset_id or url, optional role and note. Does not change the character references.
GenerateBody.source_image_asset_id on /v1/mascots/:id/generateN/AThe image to animate or edit. NOT a style reference.

Removing a reference

curl -X DELETE https://api.masko.ai/v1/mascots/MASCOT_ID/references/ASSET_ID \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

How the style card works

On a mascot's first generation, Masko extracts a style card from the references: a short description of the palette, proportions, outline style and other defining traits. It is cached on the mascot config and sent with the reference images in every prompt. Adding or removing a reference clears it, and the next generation extracts it again.

Common mistakes

  • Using a preview as a source. Previews from /v1/generate/preview are not persisted and have no asset ID. Generate the pose with POST /v1/mascots/:id/generate, then use asset_ids.image.
  • Passing a transparent_image ID as source_image_asset_id. The source must be the full image asset (asset_ids.image), not the background-removed one.
  • Confusing the source with references. source_image_asset_id is the exact pose to animate or edit; references define what the character looks like.