Canvases and releases
A canvas is the state machine behind an interactive mascot: nodes are poses, and edges are the animated transitions between them with the conditions that trigger them. A canvas belongs to a project and can mix Original and variant poses in one graph.
Create a canvas
Creating an empty draft generates no media. The mascot sets the starting identity and the project controls access.
curl -X POST https://api.masko.ai/v1/canvases \
-H "Authorization: Bearer $MASKO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"project_id":"PROJECT_ID","mascot_id":"MASCOT_ID","name":"Main Canvas"}'The response has data.id, data.graph and data.graph_content_hash. Optional variant_id sets the default identity for new poses.
curl 'https://api.masko.ai/v1/canvases?project_id=PROJECT_ID' \
-H "Authorization: Bearer $MASKO_API_KEY"
# One mascot's canvases, without their graphs
curl 'https://api.masko.ai/v1/canvases?mascot_id=MASCOT_ID&fields=summary' \
-H "Authorization: Bearer $MASKO_API_KEY"Each canvas comes with its full graph. mascot_id lists only that mascot's canvases: with project_id it narrows the project's list, and without it, it lists the mascot's canvases in every project you can open. One of the two is required. fields=summary leaves out graph, which keeps a list of large canvases small; read one canvas for its graph. Send limit and offset to page.
Edit safely
Read the draft, edit the complete graph and send its revision as expected_graph_hash. A concurrent edit returns 409, so read again before reapplying your change.
const base = 'https://api.masko.ai/v1';
const headers = { Authorization: `Bearer ${process.env.MASKO_API_KEY}` };
const read = await fetch(`${base}/canvases/${canvasId}`, { headers });
const result = await read.json();
if (!read.ok) throw new Error(result.error.message);
const draft = result.data;
const graph = structuredClone(draft.graph);
// Edit graph.nodes, graph.edges and graph.inputs here.
const saved = await fetch(`${base}/canvases/${canvasId}`, {
method: 'PATCH',
headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ graph, expected_graph_hash: draft.graph_content_hash })
});
const receipt = await saved.json();
if (!saved.ok) throw new Error(receipt.error.message);Send back everything you read: unchanged poses and edges keep their pictures and clips. An edge's prompt is animationPrompt when set, otherwise description. Studio writes both with the same text, and while they match, editing description alone changes the prompt. An edge whose prompt, duration, source, target or poses change loses its clip, even when you send its videoAssetId back, and receipt.data.edges_to_regenerate lists it: the next generate-all remakes it. To give an edge a clip the mascot already has, set videoAssetId to one the generation estimate lists under reusable.
Graph fields are in Build a canvas.
Generate and validate
Dry-run POST /v1/canvases/CANVAS_ID/generate-all to review the work and cost, then submit the same selection with approved_plan_id and expected_graph_hash. Track it with GET /v1/canvases/CANVAS_ID/status instead of resubmitting; see canvas generation. Validation and history reads are free.
Over MCP, estimate_canvas_generation gives the price and a plan_id, and generate_canvas generates that plan within max_credits, with no dry_run or approved_plan_id (over MCP).
Checkpoints and releases
{
"action": "checkpoint",
"name": "Before adding a transition",
"expected_graph_hash": "CURRENT_GRAPH_HASH"
}GET /v1/canvases/CANVAS_ID/history returns the draft, checkpoints and releases. POST one action to the same route:
| Action | Additional fields |
|---|---|
checkpoint | name, expected_graph_hash |
restore | checkpoint_id, expected_graph_hash |
release | operation_id (UUID), notes, expected_graph_hash |
restore_release | release_id, expected_graph_hash |
copy_release | release_id, name, expected_graph_hash |
- Checkpoints can hold unfinished work. A release freezes a complete, playable graph with its exact dependencies, so it needs complete media and a fresh UUID
operation_id;notesis optional. - A release the Masko player would not play is refused with 422 and the reasons: a condition it cannot read (an unknown comparison, a value that is not true, false or a number), an input without a type or starting value, a move to a pose that is not in the canvas, a speed of 0, or a pose without a picture.
- Restore saves the current work in a checkpoint first.
- No action regenerates media, spends credits, publishes content or activates a mascot on a Mac. An installed release stays pinned until explicitly replaced.
- In Studio, the button at the top right of the canvas says where the mascot is ("Not in apps yet", "Version 3 · changes", "Version 3 · in apps") and opens a panel: Send version makes a release with an optional note, and Use this version on an older release sends it back to apps as the next one (
restore_release, thenrelease).
Deliver a release
An app reads its canvas's releases with an app key of the mascot, which can only read that mascot's released canvases, so it is safe to ship. It plays them with the Masko player, which runs every canvas rule; on iPhone, iPad and Mac, MaskoPlayer(url:appKey:) asks for each new release by itself. A website asks straight from the page, with the same key. The key can also go inside the link, …/delivery?key=masko_app_…, so one link is all an app needs; the canvas panel in Studio gives that link. Play a canvas has the request, the targets and the set and fire calls. target=desktop returns the full media set, for Masko for Mac. The delivery holds signed playback links that expire within a day or two, not a credential. Never put your account API key in a website or a shipped app.
Templates and export
To start from a ready-made graph, save a canvas template into an empty draft. Export reads the graph with its media links in an older, deprecated format; apps play a release.
