Manage mascots and assets

Find project, mascot, item and asset IDs, check generation status and get CDN URLs. Create variants and publish a mascot to the Marketplace.

List projects#

A project holds one or more mascots.

curl https://api.masko.ai/v1/projects \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "data": [
#     {
#       "id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
#       "name": "My SaaS",
#       "organization_id": null,
#       "created_at": "2026-01-15T08:00:00Z",
#       "updated_at": "2026-01-15T08:00:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

List mascots#

Filter by project with the optional project_id.

# All mascots
curl https://api.masko.ai/v1/mascots \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Filter by project
curl "https://api.masko.ai/v1/mascots?project_id=75270a54-f2f9-58e5-83c0-8575c720ca86" \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "data": [
#     {
#       "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
#       "project_id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
#       "name": "Fox Mascot",
#       "type": "mascot",
#       "is_published": true,
#       "public_slug": "fox-mascot-a1b2c3d4",
#       "user_prefix": "fda8417d",
#       "created_at": "2026-02-01T10:00:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

Mascot detail#

Returns the mascot with its config: prompt, reference asset IDs, style card and caution list.

curl https://api.masko.ai/v1/mascots/8bf14263-eabc-58a4-80f6-be9e4f7bceeb \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "data": {
#     "id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
#     "name": "Fox Mascot",
#     "type": "mascot",
#     "project_id": "04dae799-dd9a-4296-ba86-9e3913c2f8d1",
#     "slug": "fox-mascot-a1b2c3d4",
#     "config": {
#       "prompt": "A friendly fox character for our SaaS",
#       "reference_asset_ids": ["e906ebb5-deb1-4010-82f9-f0182a3812e0"],
#       "style_card": null,
#       "caution_list": []
#     },
#     "room_for_movement": true,
#     "cdn_status": [],
#     "created_at": "2026-02-01T10:00:00Z",
#     "updated_at": "2026-03-15T16:20:00Z"
#   }
# }

Room for movement#

With room_for_movement on, new animations are made from the mascot's poses shrunk to 80% of their picture, so jumps, wings and raised arms stay inside the video instead of being cut off at the edge. The mascot looks 20% smaller in each file: show it in a box about 25% bigger to keep the same size. New mascots start with it on; mascots made before it existed start with it off, so their animations keep their size. Change it with PATCH /v1/mascots/:id:

curl -X PATCH https://api.masko.ai/v1/mascots/8bf14263-eabc-58a4-80f6-be9e4f7bceeb \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26" \
  -H "Content-Type: application/json" \
  -d '{ "room_for_movement": true }'

A canvas keeps one size: a new move matches the clips already on it, and only an empty canvas follows the setting. An edit keeps the size of the clip it edits.

List items#

An item is one pose or asset in a mascot. It can hold several asset types (image, animation, logo).

curl https://api.masko.ai/v1/mascots/8bf14263-eabc-58a4-80f6-be9e4f7bceeb/items \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "data": [
#     {
#       "id": "b646b856-5832-49f4-90bf-9c41a50515b3",
#       "name": "Idle",
#       "type": "image",
#       "prompt": "idle pose",
#       "public_slug": "idle",
#       "created_at": "2026-02-01T10:05:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

Check asset status#

Lists every asset in a mascot with its status, to see which generations are still running.

curl https://api.masko.ai/v1/mascots/8bf14263-eabc-58a4-80f6-be9e4f7bceeb/assets \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "data": [
#     {
#       "id": "e906ebb5-deb1-4010-82f9-f0182a3812e0",
#       "type": "image",
#       "status": "completed",
#       "file_url": "https://storage.googleapis.com/...",
#       "cdn_url": "https://assets.masko.ai/fda8417d/fox-mascot/idle.png",
#       "file_size": 245832,
#       "item_id": "b646b856-5832-49f4-90bf-9c41a50515b3",
#       "mascot_id": "f9503022-a991-46ea-bf8c-d628c921b6b0",
#       "created_at": "2026-02-01T10:05:00Z"
#     }
#   ],
#   "meta": { "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false } }
# }

Published assets include cdn_url; others include a signed file_url when available. file_size is the file's size in bytes once it is completed. Add ?include_file_urls=false to skip signed URLs for metadata-only polling (cdn_url stays).

CDN export JSON#

Returns the hosted-link JSON shown in Get Links → Export JSON. It is built from published CDN assets, so it includes pose items with attached video loops even when the item is not typed as an animation.

curl https://api.masko.ai/v1/mascots/8bf14263-eabc-58a4-80f6-be9e4f7bceeb/cdn-export \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Masko-API-Version: 2026-09-26"

# Response:
# {
#   "mascot": "Fox Mascot",
#   "items": [
#     {
#       "name": "card-sit",
#       "image": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.png",
#       "transparent_image": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-transparent.png",
#       "animations": [
#         {
#           "video": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.mp4",
#           "transparent_video_webm": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.webm",
#           "transparent_video_mov": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit.mov",
#           "transparent_video_android": "https://assets.masko.ai/fda8417d/fox-mascot/card-sit-android.mp4"
#         }
#       ]
#     }
#   ]
# }

The export also has stickers (transparent PNG URLs) and interactions (complete hosted cursor followers, each with nine image URLs). For IDs, prompts and status, use the items and assets endpoints instead.

It returns 409 cdn_export_not_ready when asset hosting is off or no file is hosted yet. Turn hosting on with Get Links or POST /v1/mascots/:id/publish (turn on hosting), or wait for the jobs to finish, then retry.

Items, assets and deletion#

• PATCH /v1/mascots/:id/items/:itemId - body { name?, prompt? }

• DELETE /v1/mascots/:id/items/:itemId

• GET /v1/assets - list your assets with pagination; add include_file_urls=false for metadata-only lists

• GET /v1/assets/:id - get a single asset

• DELETE /v1/assets/:id - archive an asset (soft delete)

Mascot variants#

A variant is a named generation context for one mascot (a different look, personality or habits) with its own approved reference image. Manage them in the mascot page's Context & References panel or with these endpoints.

Permissions follow the mascot's project: owners, admins and members with project access can manage a teammate's variants. API keys must belong to the mascot's workspace, and generation on a team mascot charges the organization balance.

The paginated response includes id, name, description, approved_at (null for a draft), reference_asset_id and canvas_id. Editing a context affects future generations only.

Pass an approved variant_id to POST /v1/mascots/{id}/generate:

{
  "type": "image",
  "name": "A curious detective",
  "variant_id": "VARIANT_UUID",
  "image_prompt": "Leaning forward with a curious expression."
}

• Images, animations, edits, logos, backgrounds, and action suggestions accept variant_id. Each /generate-batch request can pick its own.
• Omitted on a new pose, it means Original. Omitted with a source image or video, it means that asset's saved context. It never follows the active playback variant.
• A draft variant returns 409 and another mascot's variant returns 404. An ordinary animation whose source does not match the selected variant returns 409 before charging.

Transitions. Supply source_image_asset_id and end_image_asset_id; the poses may belong to different variants. The prompt writer uses each pose's saved context, and an upload without a generation receipt uses its associated context (ambiguous ones are rejected). generation_context.transition records both endpoints, the writer output and the final prompt. A cross-variant transition has variant_id: null, and reversing swaps the roles without a new writer call.

Transition edits. A type: "edit" with source_video_asset_id and edit_instructions keeps the clip's before and after identities; an explicit variant_id must match one of them. The request is recorded under generation_context.transition_edit. Video edits take 2 to 15 second sources, keep duration and aspect ratio, open and end on the poses the clip was made between, and cost 5 credits per source second, rounded up.

Canvases. Use the variant's canvas_id with the canvas endpoints. A canvas can mix Original and variant poses from the same mascot; its variant only sets the default generation context. Generating never activates a variant: activate it in the web app once its media is complete.

Create a variant through v1#

1. POST /v1/mascots/{id}/variants with a client-generated id, name, description and optional source_variant_id (omit for Original). The source context and references are frozen into the draft. Creating a draft is free.
2. POST /v1/mascots/{id}/variants/{variantId}/reference with { "operation_id": "UUID" }. Costs 1 credit and returns job_id and candidate_id. Reuse the operation ID to retry the same job.
3. Poll GET /v1/jobs/{jobId}, then read GET /v1/mascots/{id}/variants/{variantId} for candidate previews.
4. POST /v1/mascots/{id}/variants/{variantId}/approve with { "candidate_id": "UUID" }. Approval does not activate playback or generate media.
5. Pass the variant_id to /generate. The approved variant also has a canvas_id.

To skip steps 2 to 4, add reference_asset_id in step 1: a completed image from this mascot or your unassigned upload from POST /v1/upload, which gets attached to this mascot. The variant is approved at once, at no credit cost. Archived, unfinished and other-mascot images are rejected.

Reuse the creation id only with the same inputs. Only the draft's creator can generate and approve its candidates.

Publish to the Marketplace#

Submit an exact selection of a mascot's identities and assets for review. Once approved, it appears on the Marketplace or in a customer library.

1. POST /v1/mascots/MASCOT_ID/publication with {action:"start"} creates a listing or starts editing its approved version. Viewing a mascot never creates one.
2. Send {action:"preview",selection:{asset_ids:[],identity_ids:["original"]}} to the same endpoint. It returns plan_id and an exact preview.
3. Send action:"submit" with the same selection and plan_id within ten minutes. Changed content returns 409; repeating the same plan returns its existing submission.

Admins approve the frozen content; read entitled content with GET /v1/mascots/MASCOT_ID/published-library?project_id=PROJECT_ID. For a Marketplace listing, add an offer to the selection:

{
  "offer": {
    "price_credits": 0,
    "description": "A sleepy cloud mascot",
    "accept_creator_terms": true,
    "cover_asset_id": "SELECTED_ASSET_UUID"
  }
}

• Include at least one image and at least 5 animations. The mascot needs at least one completed generated image.
• description is optional.
• The cover must be an included image, not an animation or delivery export. Without cover_asset_id, an included generated image is chosen, else the first included image. Changing the cover needs a new preview.

Mac version#

Add "player_canvas_id": "CANVAS_UUID" to the selection to choose the canvas of this mascot that buyers play on Masko for Mac. Preview and submit freeze its graph as player (canvas_id, name, graph, graph_hash), and every image and animation it uses is included automatically. The graph must pass validation and use generated animations, not exported formats.

• A mascot's first Marketplace offer needs a Mac version.
• Leave player_canvas_id out to keep the approved Mac version. Removing any media it plays returns 409 Your Mac version uses media you removed; select that media again or choose a canvas.
• GET /v1/mascots/MASCOT_ID/publication returns player: the approved Mac version, whether one is required, and the mascot's canvases with their state and animation counts and any issue that blocks them.

GET /v1/mascots/MASCOT_ID/publication returns gallery assets with transparent image, WebM and HEVC URLs when available, plus has_generated_image; formats are not separate selectable assets. Its listing_preview is the offer in review, else the approved listing, else null. Send {"action": "withdraw"} to pull a submission back to draft; any published version stays live.

Library publication is separate from public CDN hosting. Approved content stays live while a later submission is in review, and new assets stay private until selected and approved. The Marketplace sells identities and assets, not canvas releases.

Buyers get a read-only shared context. Duplicating an identity creates an independent personal variant with copied context and permitted references.

Listing visibility and reviewed changes#

GET /v1/mascots/{id}/publication returns state: null before you start a listing. After that, state.visibility is unpublished, published or archived, and state.changes_status is independently draft, pending, approved or rejected.

Approval replaces the live selection, name, description, cover and price together, and makes the listing public unless it was archived during review. Existing buyers keep what they acquired. A mascot rename reaches the listing on the next approved submission.

Submitting, approval and restore require a creator handle and a public profile. Archive all published mascot libraries before making the profile private or unlisted.

Personal and organization purchases#

Buy as Personal or as an organization: each workspace owns its own license, and team credits never fall back to personal credits. Any team member can buy for the organization, ownership stays with it when the buyer leaves, and a repeated team purchase returns the existing ownership without charging. published-library?project_id=PROJECT_ID returns purchased content only for that project's workspace.

Publish as an organization#

A mascot in an organization project publishes under the organization's profile (name, handle, logo, bio). Owners and admins can edit that profile, manage the listing and submit updates, and sales go to the team's credit wallet.

GET /v1/mascots/{id}/publication returns seller.user_id or seller.organization_id (exactly one is non-null) and seller.can_publish. The project decides the seller, and submitted or published mascots cannot move to another workspace.