Hosting and file formats

Pick the file your platform plays with transparency, then serve it from Masko's CDN or your own.

File formats#

Apple browsers need HEVC for transparency, others WebM, and Android apps the stacked MP4. The Masko player picks the right file and loops it:

<div id="mascot" style="width: 240px; height: 240px"></div>
<script src="https://cdn.jsdelivr.net/npm/@masko/player@0.1/dist/masko-player.js"></script>
<script>
  MaskoPlayer.mount(document.getElementById('mascot'), {
    clip: { webm: 'https://assets.masko.ai/.../wave.webm', hevc: 'https://assets.masko.ai/.../wave.mov' }
  });
</script>

A talking animation plays its own voice. Browsers allow sound only after the person's first click or key press on the page: until then it plays muted, and its voice is heard from the next loop. Pass sound: false to keep it silent.

Hosted CDN URLs#

With hosting on, generation returns CDN URLs before the files exist. Each serves a branded placeholder until the real file replaces it at the same URL.

URL format#

https://assets.masko.ai/{user_prefix}/{mascot_slug}/{item_slug}-{hash}.{ext}

Example:
https://assets.masko.ai/fda8417d/felix-the-fox/waving-hello-a1b2c3d4.png

user_prefix is your account prefix, mascot_slug comes from the mascot's slug field, item_slug from the item name at creation, and ext from the asset type (png, mp4, webm or mov).

Size variants#

Free size variants add the size before the extension. The file size calculator shows what each size weighs.

URLs look like this:

# Original (full resolution)
https://assets.masko.ai/u/felix-the-fox/waving-a1b2.webm

# 480px variant
https://assets.masko.ai/u/felix-the-fox/waving-c3d4-480.webm

# 360px variant
https://assets.masko.ai/u/felix-the-fox/waving-e5f6-360.webm

Get variant URLs instantly#

Pass sizes when generating to get the variant URLs in the response:

{
  "type": "animation",
  "name": "wave",
  "image_prompt": "standing and waving",
  "animation_prompt": "waving hello",
  "animation_model": "standard",
  "duration": 5,
  "sizes": [480, 360]
}

urls then adds keys such as webm_480 for sizes enabled in animation_sizes, serving placeholders until ready; poll the job's size_variants.status.

Check CDN status#

GET /v1/mascots/:id returns cdn_status, with each published asset's URL, size and status.

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

List mascot assets#

Each asset has cdn_url when hosted, otherwise a signed file_url, and file_size in bytes once it is completed. Add ?include_file_urls=false to skip signing for metadata-only lists.

curl https://api.masko.ai/v1/mascots/MASCOT_ID/assets \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

Turn on hosting#

Mascots created with the API start with hosting on. Mascots made in Studio or through the MCP server start with it off. Turn it on with the Get Links switch in Studio, or with this call. Every finished image and video gets a permanent public URL, and files finished later are hosted automatically.

Anyone with a URL can open the file, so an agent should ask the mascot's owner before it calls this.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/publish \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Calling it again on a hosted mascot changes nothing and returns changed: false. Send {"force": true} to host finished files that are missing. It returns 400 when the mascot has no finished file yet. Hosting costs no credits up to 50,000 views a month, then 1 credit per 1,000 views.

Export the Get Links JSON#

GET /v1/mascots/:id/cdn-export returns the Get Links JSON of the mascot page: images, transparent images, videos, size variants, logos and stickers by item name. animated_stickers have telegram, whatsapp, wechat and discord keys in formats.

Only ready, hosted versions appear. While hosting is off, or before any file is hosted, it returns 409 cdn_export_not_ready with a message that says which one: turn on hosting, or wait for the jobs to finish.

curl https://api.masko.ai/v1/mascots/MASCOT_ID/cdn-export \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

Change the slug#

A new slug changes only future asset paths. Slugs are 2 to 50 lowercase letters, digits and dashes, unique across all mascots.

curl -X PATCH https://api.masko.ai/v1/mascots/MASCOT_ID \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "felix"
  }'

Turn off hosting#

Set settings.cdn_enabled: false when creating the mascot. Assets are still generated, with signed storage URLs from the jobs endpoint.