Skip to content
Masko logomasko
Docs
QuickstartAPI reference
Documentation

CDN URLs & Size Variants

With CDN hosting enabled, generation can return pre-allocated URLs before the files are ready. Keep a loading state until the job and required media formats are complete. A URL alone is not proof that an animation is playable.

How Instant CDN URLs Work

When you call the generate endpoint, Masko uploads a branded placeholder to the CDN path and returns the URL in the response. Your app can start using this URL immediately. Once generation completes, the real asset file replaces the placeholder at the same URL - seamlessly, with no URL change needed on your side.

This means you can build your UI, set up image tags, and configure video players before any generation finishes. The placeholder is a lightweight branded image that signals "generating" to users.

URL Format

CDN URLs follow this structure:

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 - Your account prefix, set automatically.
  • mascot_slug - Derived from the mascot name. Can be changed by patching the mascot's slug field.
  • item_slug - Derived from the item name when created.
  • hash - Short unique hash to prevent collisions.
  • ext - File extension based on asset type (png, mp4, webm, mov).

Size Variants

Configure animation_sizes in the mascot settings to generate pre-rendered size variants. Size variants are free - no extra credits.

Size variant URLs append the resolution suffix before the extension:

# 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 in the generate request to get pre-allocated CDN URLs for specific variants:

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

The response urls object includes keys like webm_480, hevc_480 alongside the originals. These URLs serve placeholders immediately and swap to real files once the size variant workflow finishes.

The sizes parameter is a filter on what you get back - it only returns URLs for sizes that are enabled in the mascot's animation_sizes config. Poll the job's size_variants.status field to know when all variants are ready.

Check CDN Status

CDN publishing status for the mascot is returned as the cdn_status field on GET /v1/mascots/:id. It lists which assets have been published, their file sizes, and current status.

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

List Mascot Assets

Retrieve assets for a mascot. Returns cdn_url when available, falling back to signed file_url. For metadata-only lists, add ?include_file_urls=false to skip signed file_url generation.

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

Export Get Links JSON

Use GET /v1/mascots/:id/cdn-export when you want the same copy-paste JSON shown in the mascot page Get Links export modal. This response is not a raw asset list: it groups images, transparent images, animation videos, size variants, and logos by item name so it can be handed directly to an app.

This endpoint only returns published CDN assets. If asset hosting is disabled, the mascot is not published, or no CDN assets exist yet, it returns 409 cdn_export_not_ready.

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

Change Slug

Update the mascot's CDN slug by patching the mascot. This changes the URL path for all future assets. Existing CDN URLs are not affected - only new publishes use the new slug.

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"
  }'

Slugs must be 2-50 characters, lowercase alphanumeric with dashes. Each slug must be unique across all mascots.

Disabling CDN

If you do not need CDN URLs, set settings.cdn_enabled: false when creating the mascot. Assets are still generated and accessible via signed storage URLs through the jobs endpoint.