MASKO STUDIO API

A little code.
A lot of character.

Create a mascot. Give it poses, motion, and a voice. Bring the finished files into your product, all through one REST API.

Get an API key Read the quickstart
See the API in action ↓Assets & canvas ↓

Small request.
Big personalities.

Patata waving hello
Otto typing with its tentacles
Gubby resting and moving gently
POST/mascots/:id/generateSame API. Your character.

Made in Studio. Available in your code.

Explore the documentation

THE REQUEST. THE CHARACTER. THE RESULT.

What will yours do first?

Pick an example. Look at the request. Meet the kind of output you can make.

A loading state with eight helping hands.

Describe a pose and a movement. Get an animation of your mascot, with transparent video exports for your interface.

Read the guide 
curl https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "animation",
  "name": "Typing",
  "image_prompt": "seated at a keyboard",
  "animation_prompt": "typing energetically with its tentacles",
  "animation_model": "standard",
  "duration": 5
}'
POST/v1/mascots/:id/generate202 Accepted

GENERATED EXAMPLE
Otto typing with its tentacles

Otto has the typing covered.

WebMHEVCMP4

Example requests and recorded outputs. To generate your own, replace the IDs and run the request on your server with your API key.

ONE MASCOT. A WHOLE CAST OF ASSETS.

From the first sketch
to the last little detail.

Six ways to put your character to work. See what each asset does, what you get back, and the API request that creates it. Your mascot’s references keep the character consistent.

Rosa mascot poseTheo mascot poseMilo mascot pose

Images & poses.

Describe an expression, outfit, or action. Generate a new still image of your mascot for an avatar, onboarding screen, or the starting pose of an animation.

ImageTransparent image

POST/v1/mascots/:id/generate

See the API request

Generate an image

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "image",
  "name": "Welcome",
  "image_prompt": "waving hello with a big smile"
}'

Replace the uppercase IDs. Run on your server with your API key. These requests use generation credits.

Image generation
Otto typing with its tentacles
Acorn celebrating a completed lesson

Animations & speech.

Animate a saved pose, or describe a new pose and its movement together. For a talking clip, start from a saved pose and give your voiced mascot a script with words and gestures.

Transparent videoAudio + transcript

POST/v1/mascots/:id/generate

See the API request

Generate an animation

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "animation",
  "name": "Welcome wave",
  "image_prompt": "standing with one hand raised",
  "animation_prompt": "waves hello, then returns to the starting pose",
  "animation_model": "standard",
  "duration": 5
}'

Generate a talking clip

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "animation",
  "name": "Spoken welcome",
  "source_image_asset_id": "SOURCE_IMAGE_ASSET_ID",
  "speech": {
    "script": "[waves hello, excited] Welcome aboard!"
  }
}'

Replace the uppercase IDs. Run on your server with your API key. These requests use generation credits.

Animation generation
Otto as a bashful stickerGubby as a joyful sticker

Stickers.

Turn a completed mascot image into a transparent PNG with a white sticker border. Keep the pose and add a little personality to messages, rewards, and your interface.

Transparent PNGWhite border

POST/v1/assets/:id/sticker

See the API request

Generate a sticker

curl -X POST https://api.masko.ai/v1/assets/IMAGE_ASSET_ID/sticker \
  -H "Authorization: Bearer $MASKO_API_KEY"

Replace the uppercase IDs. Run on your server with your API key. These requests use generation credits.

Sticker generation
Rudy the dog mascotRudy as a graphic app icon

Choose a composition and a visual style. Turn your character into a face icon, badge, or brand mark, with a master image, transparent version, resized PNGs, and a favicon.

PNG + faviconOptional SVG generation

POST/v1/mascots/:id/generate

See the API request

Generate an app icon

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "logo",
  "name": "App icon",
  "logo_description": "A face-only icon of the character",
  "logo_style_id": "graphic-app-icon"
}'

Replace the uppercase IDs. Run on your server with your API key. These requests use generation credits.

Logo generation
Otto in an underwater scene

Scenes.

Put your mascot in a setting. Describe the environment and the action separately, then choose the aspect ratio for a hero illustration, story, or campaign image.

Scene imageLandscape, square, portrait

POST/v1/mascots/:id/generate

See the API request

Generate a scene

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "scene",
  "name": "Under the sea",
  "scene": "A deep blue ocean with soft glowing sea plants",
  "action": "Playing a small keyboard on the ocean floor",
  "aspect_ratio": "4:3",
  "position": "center"
}'

Replace the uppercase IDs. Run on your server with your API key. These requests use generation credits.

Scene generation
Move your cursor, or tap an arrow.

Cursor interactions.

Turn a completed transparent pose into nine gaze directions. Your site swaps the images so the character follows the pointer. Use a canvas for reactions between animated states.

9 directional imagesReact or JavaScript

POST/v1/mascots/:id/interactive

See the API request

Generate a cursor follower

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/interactive \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "source_asset_id": "SOURCE_IMAGE_ASSET_ID",
  "kind": "cursor-follower",
  "name": "Website cursor follower"
}'

Replace the uppercase IDs. Run on your server with your API key. These requests use generation credits.

Cursor interaction generation

Requests and recorded examples. Generation uses workspace credits. Follow the returned job or asset status before using the files. Want reactions between animated states? Create a canvas ↓

GIVE THE ANIMATIONS A LITTLE LOGIC.

A clip moves.
A canvas reacts.

A canvas is a state machine: poses are nodes, animated moves are edges, and input conditions decide which move plays. Connect your app events to those inputs to make your mascot respond.

ONE CHARACTER. TWO STATES. A MOVE BETWEEN THEM.
Dumple resting in a canvas state
RestA pose with its own loop.
Dumple moving from resting to playing
The moveA generated transition clip.
Dumple playing in a canvas state
PlayA different pose and loop.
Your app requests a reaction. The player checks the graph’s conditions, plays the connecting move, then loops in the new state. Playback uses finished media; each interaction needs no new generation request.
Try an interactive canvas

START WITH ONE REQUEST

Create your canvas through the API.

Use your project and mascot IDs. This creates an empty draft; generating its poses and moves is a separate step.

curl -X POST https://api.masko.ai/v1/canvases \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": "PROJECT_ID",
  "mascot_id": "MASCOT_ID",
  "name": "Product reactions"
}'
Build a canvas step by step
  1. 01

    Create a canvas.

    Start an empty project canvas with your mascot. Save the returned canvas ID and graph hash.

    POST/v1/canvases
  2. 02

    Connect the reactions.

    Add pose nodes, animation edges, and input conditions. Save the graph with expected_graph_hash so a newer edit stays safe.

    PATCH/v1/canvases/:id
  3. 03

    Generate the moves.

    Preview the work and cost with dry_run: true. Execute with the approved_plan_id and graph hash, then follow the returned jobs until the media is ready.

    POST/v1/canvases/:id/generate-all
  4. 04

    Bring it into your app.

    Enable hosting and wait for the required media. Export the player configuration and connect your app events to its declared inputs.

    GET/v1/canvases/:id/export

FROM YOUR BACKEND TO YOUR FRONTEND

Four steps.
One new teammate.

Generate on your server. Display the finished assets wherever your product needs a little personality.

  1. 01
    POST /v1/mascots

    Create your mascot.

    Create a project, then a mascot from your prompt or images. Already made one in Studio? Use its ID.

    Create a mascot
  2. 02
    POST /v1/mascots/:id/generate

    Request an asset.

    Choose the asset and describe what you need. Save the job ID from the accepted request.

    Pose-to-animation guide
  3. 03
    GET /v1/jobs/:id

    Follow the generation job.

    Poll for completion or receive a webhook. Check each export is ready before putting its file on screen.

    Follow a generation job
  4. 04
    GET /v1/assets/:id

    Use the finished files.

    Download images and videos, or use ready CDN URLs. Your app decides when and where the mascot appears.

    Files, exports & hosting

THE PRACTICAL PART

Cute on the frontend.
Clear on the backend.

Your stack is welcome.

REST, JSON, and Bearer authentication. Use fetch, cURL, Python, or the HTTP client you already have.

Start with the quickstart

Let the job come to you.

Receive signed completion and failure webhooks instead of keeping your app in a polling loop.

Set up webhooks

Choose your delivery.

Transparent images, WebM, and HEVC exports. Download your files or enable Masko CDN hosting.

Files & CDN hosting

Know what to send.

Endpoint schemas, error codes, API versions, and retry conventions, all in the reference.

Open the API reference

Building with an AI coding agent? Give it the Masko API skill.

Get the skill

THE LITTLE DETAILS

Before you say hello.

A few things your backend might ask.

Can I generate every asset type through the API?

Yes. Images, animations, talking clips, logos, and scenes use the mascot generation endpoint. Stickers use a completed image asset; cursor followers use the interactive endpoint. Each example above shows its request. Canvases have their own creation, graph, generation, and export routes.

Explore generation options →
How do I make an animation interactive?

Use a canvas to connect poses with animated moves and conditions. Your app sets the declared inputs when something happens, such as a user interaction or a completed task. The player chooses the next state and plays the connecting clip. Playback uses generated media; it does not generate a new video for every interaction.

Build an interactive canvas →
Can I use a mascot I already made in Studio?

Yes. Use a key from the same workspace and the ID of your existing mascot. Studio and the API work with the same mascots, poses, and assets.

How mascots work →
Can I create the character through the API too?

Yes. Start from a text description, upload a reference image, or let Masko read a website. Your mascot keeps its references for the poses, animations, and design assets you generate next.

Create your first mascot →
Where do I put the API key?

Keep it on your server, in an environment variable. Your backend makes the generation requests; your frontend displays the finished files. Any language that can make an HTTP request can use the API.

Authentication and quickstart →
How do I know when the files are ready?

Generation returns a job ID. Poll the job or subscribe to completion and failure webhooks. Some exports finish after the main job, so check that each asset is completed before displaying its file.

Jobs and asset readiness →
Do I have to host the results myself?

You can download the files and host them with your app, or enable Masko CDN hosting. Download URLs can expire. For hosted media, use the returned CDN URL once the export is ready.

Exports and hosting →
How is API generation billed?

Generation uses your workspace credits. The cost depends on the asset type, animation model, and duration. The credit guide lists the current costs and explains how to check your balance.

See generation costs →

YOUR NEXT FEATURE HAS A FACE.

Give your product
a little character.

Get a key. Make your first request. Meet your mascot.

Get an API key Read the quickstart
Disco Patata, ready to celebrate your first API request