Quickstart: your first animation

Create a mascot from a description and get a five-second transparent animation of it waving, in four calls. It uses 12 credits: 1 for the reference image, 1 for the pose and 10 for the Standard video.

Ko, in a transparent animation like yours. To check the pose before paying for video, follow the pose-to-animation walkthrough instead.

You need a write key from API keys and enough credits. Run requests on a server or in a terminal, never with the key in browser code, and replace uppercase IDs with values from earlier steps.

Step 1: Create a project#

Projects group related mascots.

curl -X POST https://api.masko.ai/v1/projects \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My App" }'

Step 2: Create a mascot#

Without reference images, Masko draws the first one from your prompt for 1 credit.

curl -X POST https://api.masko.ai/v1/mascots \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Felix the Fox",
    "project_id": "PROJECT_ID",
    "prompt": "A friendly orange fox mascot wearing a blue scarf"
  }'

Step 3: Generate an animation#

This five-second Standard request costs 11 credits, including its new pose image (31 with "premium"), and returns a job ID.

curl -X POST https://api.masko.ai/v1/mascots/MASCOT_ID/generate \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "animation",
    "name": "Waving hello",
    "image_prompt": "waving hello",
    "animation_prompt": "waving hello with a friendly hand wave",
    "animation_model": "standard",
    "duration": 5
  }'

Step 4: Get the result#

Poll the job until completed or failed, stopping on HTTP errors. A client timeout does not cancel accepted work.

data.poll_url is a masko.ai path (/api/v1/jobs/...); with https://api.masko.ai, build the URL from the job ID:

curl https://api.masko.ai/v1/jobs/JOB_ID?api_version=2026-09-26 \
  -H "Authorization: Bearer $MASKO_API_KEY"

# Response:
# {
#   "data": {
#     "id": "JOB_ID",
#     "status": "completed",
#     "type": "item_generation",
#     "urls": {
#       "video": "https://...",
#       "webm": "https://..."
#     }
#   }
# }

Play webm in Chrome, Firefox and Edge and the HEVC .mov on Apple devices (hosting and file formats). URLs can exist before their file, so wait for completed.

Next steps#