REST quickstart

Use the canonical /v1/mascots and /v1/canvases endpoints on https://api.masko.ai. For local testing, use http://localhost:3000/api/v1. Existing /v1/collections integrations remain supported. See the migration guide.

Create a character and generate a five-second Standard animation. This example uses 12 credits: 1 for the initial reference, 1 for the animation’s source image, and 10 for the video.

The sequence is project → mascot → generation job → completed files. For a walkthrough that lets you review the pose before animating, use pose-to-animation generation.

Create a write-capable key in API keys and check your credit balance. Run requests on your server or in a terminal, never with a secret key embedded in browser code. Replace uppercase IDs with values returned by earlier steps.

Step 1: Create a Project

Projects group related mascots together. Create one to get started.

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

A mascot represents a single mascot character. Give it a name and a prompt describing the character you want. If you create from text without reference images, Masko generates the first reference image 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

Request a generation by specifying the type, item name, and prompts. The API returns a job ID you can poll for status. This five-second Standard example costs 11 credits, including its new source image. Change animation_model to premium for higher quality at 31 credits.

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: Check the Result

Save data.job_id from the generation response. Poll until completed or failed, and stop on HTTP errors. A client timeout does not cancel accepted work. The returned data.poll_url can use the app-relative /api/v1 path; the examples below construct the public endpoint 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://..."
#     }
#   }
# }

Check the required media formats before playing the result. Some URLs are allocated before processing finishes; a returned URL is not a readiness signal.

Next Steps