CDN URLs & Size Variants

Every generation returns CDN URLs immediately, before the assets finish generating. You can embed these URLs in your app right away - they work from the moment you receive them.

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}/{collection_slug}/{item_slug}-{hash}.{ext}

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

• user_prefix - Your account prefix (e.g. u), set automatically.
• collection_slug - Derived from the collection name. Can be changed by patching the collection'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 collection 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",
  "animation_prompt": "waving hello",
  "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 collection'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 collection is returned as the cdn_status field on GET /v1/collections/:id. It lists which assets have been published, their file sizes, and current status.

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

List Collection Assets

Retrieve every published asset for a collection, grouped by item. Returns CDN URLs when available, falling back to signed storage URLs.

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

Change Slug

Update the collection's CDN slug by patching the collection. 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/collections/COLLECTION_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 collections.

Disabling CDN

If you do not need CDN URLs, set cdn_enabled: false in the collection settings when creating or updating the collection. This skips placeholder uploads and CDN URL allocation. Assets are still generated and accessible via signed storage URLs through the jobs endpoint.