Animations

Generate animated mascot videos from scratch or from existing images. All animation types use the same generate endpoint with type: "animation".

Image + Animation (New)

Generate a new image and animate it in one request. Provide both an image_prompt (for the pose) and an animation_prompt (for the motion). This costs 1 credit for the image plus 5 credits per second of video - a 4-second animation costs 21 credits total.

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "Idle breathing",
    "image_prompt": "standing relaxed with arms at sides",
    "animation_prompt": "gentle breathing motion, subtle body sway",
    "duration": 4,
    "loop": true
  }'

Animate Existing Image

Animate an image you already have by passing source_image_asset_id. This skips image generation, so you only pay for the video - 20 credits for 4 seconds.

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "Waving animated",
    "source_image_asset_id": "ast_img_001",
    "animation_prompt": "waving hello with smooth arm motion",
    "duration": 4,
    "loop": true
  }'

Transitions

Create a transition between two poses by providing both source_image_asset_id and end_image_asset_id. Transitions automatically set loop: false since they play once between two states. Costs 20 credits for 4 seconds.

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "Idle to Wave",
    "source_image_asset_id": "ast_img_idle",
    "end_image_asset_id": "ast_img_wave",
    "animation_prompt": "smoothly transitioning from idle stance to waving",
    "duration": 4
  }'

Auto-Reverse

When creating a transition, set auto_reverse: true to automatically generate the return transition (B to A) at 0 extra credits. The response includes a reverse_job with its own job ID and asset IDs.

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "Idle to Wave",
    "source_image_asset_id": "ast_img_idle",
    "end_image_asset_id": "ast_img_wave",
    "animation_prompt": "transitioning from idle to waving",
    "auto_reverse": true,
    "reverse_name": "Wave to Idle",
    "duration": 4
  }'

Duration & Looping

The duration field accepts values from 3 to 10 seconds. Default is 4 seconds. The cost formula is 5 x duration credits for the video portion.

The loop field defaults to true for standard animations and is automatically set to false for transitions (when end_image_asset_id is provided). Looping animations seamlessly repeat; non-looping animations play once and hold the last frame.

Output Formats

Every animation produces multiple format variants optimized for different platforms:

Size Variants

By default, animations are generated at full resolution. You can configure a collection to automatically produce smaller size variants for each animation - useful for responsive layouts, thumbnails, or mobile-optimized assets.

curl -X PATCH https://api.masko.ai/v1/collections/COL_ID/settings \
  -H "Authorization: Bearer masko_..." \
  -H "Content-Type: application/json" \
  -d '{
    "publish_params": {
      "animation_sizes": {
        "enabled": true,
        "sizes": [480, 360, 240]
      }
    }
  }'

Available sizes are 720, 480, 360, and 240 pixels. When enabled, every new animation automatically generates resized variants alongside the original. Existing animations in the collection are also resized retroactively.

Instant CDN URLs for Size Variants

When generating an animation, pass the sizes array to get pre-allocated CDN URLs for specific size variants immediately in the response:

curl -X POST https://api.masko.ai/v1/collections/COL_ID/generate \
  -H "Authorization: Bearer masko_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "wave",
    "image_prompt": "standing with a smile",
    "animation_prompt": "waving hello",
    "duration": 3,
    "sizes": [480]
  }'

The response includes both original and variant URLs:

{
  "urls": {
    "webm": "https://assets.masko.ai/.../wave.webm",
    "hevc": "https://assets.masko.ai/.../wave.mov",
    "webm_480": "https://assets.masko.ai/.../wave-480.webm",
    "hevc_480": "https://assets.masko.ai/.../wave-480.mov",
    "stacked_video_480": "https://assets.masko.ai/.../wave-480.mp4"
  }
}

The sizes parameter is a filter - it only returns URLs for sizes that are enabled in the collection settings. If you request sizes: [720] but the collection only has [480, 360] configured, no 720 URLs are returned.

All variant URLs serve placeholders immediately and are replaced with the real resized files when the size variant workflow completes. Poll the job to check size_variants.status.

Cost Reference

Summary of animation costs at the default 4-second duration: