Animations
Animate your mascot on a transparent background: a loop that repeats, or a transition from one pose to another. Each animation comes as a transparent WebM (Chrome, Firefox, Edge), a transparent HEVC .mov (Safari, Apple devices) and an MP4.
Ko's idle loop at its 360-pixel size.
Upload and animate in one request
Upload the image with POST /v1/upload, then animate its data.asset_id. create_mascot creates the mascot in the same request:
curl -X POST https://api.masko.ai/v1/animations \
-H "Authorization: Bearer $MASKO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: first-wave-001" \
-d '{
"source_image_asset_id": "UPLOADED_IMAGE_ID",
"create_mascot": { "project_id": "PROJECT_ID" },
"name": "Wave",
"animation_prompt": "0.00-1.00s: lifts one hand to shoulder height with a warm smile, feet planted. 1.00-3.40s: waves gently side to side in an easy rhythm. 3.40-5.17s: keeps waving at the same pace, feet still planted, into the next wave.",
"animation_model": "standard",
"duration": 5
}'- Defaults: Standard, 5 seconds, looping, $1.25. Naming, mascot creation and cropping are free; non-square images get a centered square crop (image framing).
- Without
create_mascot.name, AI picks a short name from the image that no other mascot in the project uses, adding a number such as "Pip 2" if it must (Mascot <suffix>if naming fails), and writes no description. The upload becomes the mascot's first reference as is. - The
202response hasdata.mascot_id,mascot_name,mascot_created,job_id,item_id,asset_ids,estimated_costandpoll_url.
Each create_mascot makes a new mascot, so send the returned mascot_id for the next animation of that character:
{
"mascot_id": "RETURNED_MASCOT_ID",
"source_image_asset_id": "UPLOADED_IMAGE_ID",
"name": "Bounce",
"animation_prompt": "0.00-1.30s: sinks into a soft little bounce. 1.30-2.60s: rises gently on the rebound. 2.60-3.90s: sinks into the next soft bounce. 3.90-5.17s: rises again, keeping the gentle rhythm."
}Send exactly one of mascot_id (optionally with variant_id) or create_mascot. Retry an uncertain response with the same Idempotency-Key and body; if generation fails after the mascot was created, reuse error.details.mascot_id with a new key.
New pose and animation
Send an image_prompt for the pose and an animation_prompt for the motion. Five seconds cost $1.38 ($0.125 for the image).
The animation_prompt is one action in precise time ranges that end at the clip's real length (a Standard 5 s clip is 5.17 s), and a loop's last range keeps the action going instead of returning: see write good requests.
curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
-H "Authorization: Bearer masko_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "animation",
"animation_model": "standard",
"name": "Idle breathing",
"image_prompt": "standing relaxed with arms at sides",
"animation_prompt": "0.00-1.70s: breathes in slowly, body swaying a little to one side. 1.70-3.40s: breathes out, easing back the other way. 3.40-5.17s: breathes in again with the same calm sway.",
"duration": 5,
"loop": true
}'Animate an existing image
Pass source_image_asset_id to skip image generation: $1.25 for 5 seconds with Standard. A pose's transparent_image ID works too: Masko animates the picture it was cut from.
curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
-H "Authorization: Bearer masko_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "animation",
"animation_model": "standard",
"name": "Waving animated",
"source_image_asset_id": "3c8ce568-35ce-59c2-b3f8-9fb7e4a16e52",
"animation_prompt": "0.00-1.00s: lifts one arm beside its head with a bright smile. 1.00-3.00s: waves hello side to side, smooth and friendly. 3.00-5.17s: keeps waving smoothly, the arm still raised, into the next wave.",
"duration": 5,
"loop": true
}'Transitions
Send both source_image_asset_id and end_image_asset_id; loop becomes false. $1.25 for 5 seconds with Standard.
curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
-H "Authorization: Bearer masko_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "animation",
"animation_model": "standard",
"name": "Idle to Wave",
"source_image_asset_id": "6aec5b1a-cb7f-5f10-8d6e-235ec16b4d97",
"end_image_asset_id": "18d4fd5e-7193-57f1-8af9-f3bdff007783",
"animation_prompt": "0.00-1.80s: shifts its weight and starts lifting one arm from its side. 1.80-4.30s: raises the arm beside its head, palm opening, smile brightening. 4.30-5.17s: arrives in the waving pose.",
"duration": 5
}'Variant context. A loop uses its source pose's saved context, even on a canvas that defaults to Original, and a transition keeps its start and end contexts separately.
- A conflicting
variant_idreturns409, unless that variant lists the image among its references. - An upload with no generation receipt uses the
variant_idthat references it, else Original if it does, else the only variant that does. - If several variants share an upload and Original does not, the request returns
409before charging. Pick a variant or generate distinct poses first.
Auto-reverse
On a transition, auto_reverse: true also makes the return clip (B to A), named by reverse_name, at no extra cost. It comes back as reverse_job.
curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
-H "Authorization: Bearer masko_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "animation",
"animation_model": "standard",
"name": "Idle to Wave",
"source_image_asset_id": "6aec5b1a-cb7f-5f10-8d6e-235ec16b4d97",
"end_image_asset_id": "18d4fd5e-7193-57f1-8af9-f3bdff007783",
"animation_prompt": "0.00-1.80s: shifts its weight and starts lifting one arm from its side. 1.80-4.30s: raises the arm beside its head, palm opening, smile brightening. 4.30-5.17s: arrives in the waving pose.",
"auto_reverse": true,
"reverse_name": "Wave to Idle",
"duration": 5
}'Models, duration and looping
animation_model works on /generate, each generate-batch request, and canvas edge and generate-all requests.
animation_model | Duration | Default | Price per second |
|---|---|---|---|
standard | 2–15 whole seconds | 5s | $0.25 |
Leaving animation_model out uses standard.
A duration outside the range returns 400 before charging. loop defaults to true (false for transitions) and asks for a seamless clip; your player decides whether to repeat it.
Output formats
Each animation has video (MP4, opaque), webm (VP9 with alpha), hevc (MOV with alpha) and stacked_video (MP4 with color and alpha stacked, for Android). See hosting and file formats.
Size variants
Every animation has its files at 720 px. Set up to two smaller animation_sizes, such as 480, 360, 240 or 128, in the mascot settings to get free resized copies of new animations. Sizes of 720 or more are ignored, and a third smaller size is refused.
curl -X PATCH https://api.masko.ai/v1/mascots/MASCOT_ID/settings \
-H "Authorization: Bearer masko_..." \
-H "Content-Type: application/json" \
-d '{
"publish_params": {
"animation_sizes": {
"enabled": true,
"sizes": [480, 240]
}
}
}'For finished animations, call the backfill with an empty body. It uses the configured sizes, or [360], and makes only the files each animation lacks: WebM, HEVC, stacked MP4 and stacked AV1, at its own width and at each size. Files that exist keep their links, and animations made before AV1 get their AV1 files.
curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/size-variants \
-H "Authorization: Bearer masko_..." \
-H "Content-Type: application/json" \
-d '{}'Do not toggle the settings to force a backfill. force: true regenerates existing variants, for explicit recovery only.
Instant CDN URLs for size variants
Pass sizes when generating to get variant URLs at once:
curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
-H "Authorization: Bearer masko_..." \
-H "Content-Type: application/json" \
-d '{
"type": "animation",
"animation_model": "standard",
"name": "wave",
"image_prompt": "standing with a smile",
"animation_prompt": "0.00-1.00s: lifts one arm beside its head with a bright smile. 1.00-3.00s: waves hello side to side, smooth and friendly. 3.00-5.17s: keeps waving smoothly, the arm still raised, into the next wave.",
"duration": 5,
"sizes": [480]
}'Only sizes enabled in the settings come back, and each URL serves a placeholder until its file is ready; poll the job's size_variants.status.
Direct uploads
source_image_asset_id also takes your own unattached POST /v1/upload image. It is imported as a source under the mascot, with the original file kept, no image generation and no change to mascot references. A new upload can take an approved variant_id; existing sources keep their context.
Image framing
Animations use square images. Other images, including those from item_id and transition end frames, are center-cropped into a separate 1024 × 1024 source; originals and references stay unchanged, and cropping is free.
For an off-center character, set source_image_crop:
{
"type": "animation",
"name": "Wave",
"source_image_asset_id": "IMAGE_ASSET_ID",
"source_image_crop": { "x": 200, "y": 0, "width": 800, "height": 800 },
"animation_prompt": "0.00-1.00s: lifts one hand with a warm smile. 1.00-3.40s: waves gently side to side in an easy rhythm. 3.40-5.17s: keeps waving at the same pace into the next wave.",
"animation_model": "standard",
"duration": 5
}- Coordinates are integer pixels after EXIF orientation; this takes 800 × 800 from an image at least 1000 × 800.
- The crop must be square (within one pixel) and inside the image, or the request returns
400before any job or charge. end_image_cropcrops the end frame and needsend_image_asset_id. Crops do not apply when reversing a video.
