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, or you can pass a template_id to populate it with a pre-built set of nodes and edges in the same call.

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"
  }'

Create from a Template

Templates define a pre-built set of nodes and edges. Pass template_id to the same POST /canvases endpoint to populate the new canvas with poses and transitions and kick off image generation for each node.

# Create a new canvas from the Claude Code 4-state template
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",
    "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.

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

Canvas generation progress is returned as the status field on the canvas detail response. Poll GET /v1/collections/:id/canvases/:canvasId and read status to see completion percentages and individual asset statuses.

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

# Response:
# {
#   "data": {
#     "id": "...",
#     "graph": { ... },
#     "status": {
#       "total_jobs": 12,
#       "completed": 8,
#       "pending": 3,
#       "failed": 1,
#       "progress": 0.67,
#       "ready": false
#     }
#   }
# }

Export

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

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 as template_id when calling POST /v1/collections/:id/canvases.

Custom Templates

You can save your own templates from an existing canvas or from a raw JSON definition, then apply them to any collection. This lets you reuse state machine graphs across projects.

curl -X POST https://api.masko.ai/v1/canvas-templates \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Custom Template",
    "description": "3-state widget with hover and click",
    "template": {
      "nodes": [
        { "key": "idle", "name": "Idle", "imagePrompt": "standing relaxed", "position": { "x": 0, "y": 0 } },
        { "key": "active", "name": "Active", "imagePrompt": "alert and ready", "position": { "x": 300, "y": 0 } }
      ],
      "edges": [
        {
          "source": "idle", "target": "active",
          "duration": 4, "description": "becoming alert",
          "conditions": [{ "input": "clicked", "op": "==", "value": true }]
        }
      ],
      "inputs": [
        { "name": "agent::isWorking", "type": "boolean", "default": false, "system": true }
      ]
    }
  }'

The response includes the template ID. Use it with template_id in the canvas create call to apply it to a new canvas:

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": "My Canvas", "template_id": "TEMPLATE_ID" }'

See Canvas Templates for the full reference including node/edge overrides and listing templates.