How Mascots Work

Understanding the data model behind Masko's API.

The Hierarchy

Projects own mascots and independent canvases. Within a mascot, items represent poses or actions and assets are the actual files. Canvases reference authorized mascot assets; they are not owned by one 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

Use /v1/mascots for character identity, references and generation settings. Each mascot has Original context and optional named variants. Approved shared context is read-only; duplicate it to create an independent personal variant. Future poses use current approved context, while existing generated media stays unchanged.

Legacy /v1/collections routes and payload keys such as collection_id remain compatible during migration. They identify the same mascot records.

Items

An item is a single pose or action for the mascot - like "Wave", "Idle", or "Thumbs Up". Each item has a name, a prompt describing the action, and a type (image, animation, or logo).

When you generate an image for an item, the API combines the mascot's character prompt with the item's action prompt to produce a consistent result.

Assets

An asset is a single generated file. Each item can have multiple assets of different types:

Generation Graph

Assets are connected through a generation graph. When you generate an animation, the API first creates an image, then removes the background, then animates it, then converts to web formats. Each step links back to its source via the generation_links table.

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

The role field on each link indicates the relationship. source means "this asset was derived from that asset". end_frame is used for animations where a final pose image guides the motion.

Reference Images & Style Cards

Each mascot can have up to 6 reference images. These are examples of what the mascot looks like - they guide every generation to maintain visual consistency.

When you first generate an image, Masko automatically extracts a style card from the references. The style card is a structured summary of the character's visual traits (colors, proportions, line style, shading) that gets injected into every prompt. If you change the references, the style card is cleared and re-extracted on the next generation.

A mascot’s caution_list, when configured, adds consistency instructions to generation prompts. Review generated results yourself; this is not a guarantee of automatic visual validation.

Size Variants

Animations can be generated at multiple sizes simultaneously. Set settings.animation_sizes when creating a mascot, or update publish_params.animation_sizes later, to define numeric pixel sizes such as [720, 480, 360, 240]. Resizing is free - you only pay credits for the base animation generation.

Canvases, releases and publication

A canvas belongs to a project and references mascot content. Use /v1/canvases to create and edit it. Checkpoints preserve unfinished work; releases freeze complete graphs and their exact media. Creating a release does not generate media, publish a library or activate a Desktop installation.

The marketplace sells selected mascot libraries only. Library publication and canvas releases are separate. See Studio migration for history, review and signed release delivery. The separate namespace/name character registry is retired in the Studio backend.