Canvas & Templates

A canvas is an interactive state machine for your mascot. Define poses (nodes), transitions (edges), conditions, and input triggers to create mascots that react to user actions in real time.

Concepts

Create a Canvas

Create a canvas within a collection. A canvas starts empty - you add nodes and edges by applying a template or building manually.

POST/v1/collections/:id/canvases
curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/canvases \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Canvas"
  }'

Apply a Template

Templates define a pre-built set of nodes and edges. Applying a template populates the canvas with poses and transitions, then generates all the required images and animations.

POST/v1/collections/:id/canvases/:canvasId/from-template
# Apply the Claude Code 4-state template
curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/canvases/CANVAS_ID/from-template \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "claude-code-4state"
  }'

Generate All Animations

Once your canvas has nodes with images, generate all the transition animations between connected poses in a single call. Transitions use auto_reverse by default, so reverse animations are generated for free.

POST/v1/collections/:id/canvases/:canvasId/generate-all
curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/canvases/CANVAS_ID/generate-all \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json"
Tip

Reverse transitions are free (0 credits). When generating a transition from A to B with auto_reverse, the B to A animation is created automatically at no additional cost.

Check Progress

Get the generation status of all nodes and edges in a canvas. Returns completion percentages and individual asset statuses.

GET/v1/collections/:id/canvases/:canvasId/status
curl https://api.masko.ai/v1/collections/COLLECTION_ID/canvases/CANVAS_ID/status \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

# Response:
# {
#   "canvas_id": "...",
#   "total_jobs": 12,
#   "completed": 8,
#   "pending": 3,
#   "failed": 1,
#   "progress": 0.67
# }

Export

Export the canvas as a MaskoAnimationConfig JSON object ready to use with the Masko embed player. All asset URLs point to the CDN.

GET/v1/collections/:id/canvases/:canvasId/export
curl https://api.masko.ai/v1/collections/COLLECTION_ID/canvases/CANVAS_ID/export \
  -H "Authorization: Bearer masko_YOUR_API_KEY"

Built-in Templates

These templates are available out of the box. Use the template ID when calling the from-template endpoint.