How mascots work

How projects, mascots, items and assets fit together in the Masko API.

The hierarchy#

Projects own mascots and canvases. A mascot holds items (poses or actions), and items hold assets (files); canvases use mascot assets without belonging to a mascot.

Project
  └── Mascot (identity, variants and assets)
        ├── Item: "Wave"
        │     ├── Asset: image (pose.png)
        │     ├── Asset: transparent_image (pose_nobg.png)
        │     ├── Asset: video (wave.mp4)
        │     ├── Asset: webm (wave.webm)
        │     └── Asset: hevc (wave.mov)
        ├── Item: "Idle"
        │     └── ...
        └── Item: "Thumbs Up"
              └── ...

Mascots and variants#

/v1/mascots holds identity, references and generation settings. Each mascot has an Original context and optional named variants; shared approved context is read-only, so duplicate it for your own variant. New poses use the current context, and existing media never changes.

Items#

An item is one pose or action, such as "Wave", with a name, a prompt and a type (image, animation or logo). Its prompt is combined with the mascot's character prompt.

Assets#

An asset is one generated file:

Generation graph#

Each file links to the file it was made from:

image (.png)
  └── transparent_image (.png)    [role: source]
        └── video (.mp4)          [role: source, end_frame]
              ├── webm (.webm)    [role: source]
              └── hevc (.mov)     [role: source]

A link's role is source (derived from that asset) or end_frame (the final pose guiding an animation).

Reference images and style cards#

Up to 6 reference images guide every generation. On the first generation, Masko extracts from them a style card (colors, proportions, line style, shading) that joins every prompt; changing references clears it until the next generation.

A configured caution_list adds consistency instructions to prompts but does not validate results.

Size variants#

Set settings.animation_sizes at creation, or publish_params.animation_sizes later, to get each animation at up to two smaller sizes such as [480, 240], for free. Every animation already has its 720 px files, so 720 and larger sizes are ignored.

Canvases, releases and publication#

A canvas belongs to a project and is edited with /v1/canvases. Checkpoints keep unfinished work and releases freeze complete graphs with their media, without generating media, publishing a library or activating a mascot on a Mac (canvases and releases).

Marketplace libraries are published separately from canvas releases (publish to the Marketplace).