Generate Canvas Assets

Generate pending node images and/or transition videos for your canvas. Use dry_run: true first. The plan returns plan_id and graph_content_hash; send both back when executing so Masko rejects a changed graph, prompt, or selection before spending credits.

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" \
  -d '{
    "dry_run": true,
    "targets": "animations",
    "edge_ids": ["wave-entry", "wave-loop"],
    "skip_completed": true,
    "duration": 4
  }'

How It Works

The endpoint scans the canvas and dispatches missing node images and/or edge videos based on targets. The skip_completed parameter defaults to true, meaning graph parts that already have assigned assets are skipped so running the endpoint twice does not duplicate in-flight or completed work.

Use node_ids and edge_ids to plan an exact graph selection. Omit either field to consider every part in that category. Unknown IDs are rejected before any job is created or credit is spent. Execute with the returned plan_id as approved_plan_id and graph_content_hash as expected_graph_hash. A changed graph, prompt, option, or selection returns 409 instead of silently changing approved work.

The response separates generation accounting into:

• dry_run: true when no jobs/assets were created and no credits were deducted.
• plan_id: identity of the exact graph, prompts, scope, and generation options.
• graph_content_hash: canvas revision used to create the plan.
• planned_jobs: node, sticker, and edge work that would be queued, including prompts. Planned animation and sticker jobs include signed source/target asset URLs when those input images already exist; media that would be generated by the run is represented by its prompt and cost, not a fake preview URL.
• generated: newly queued node or edge jobs.
• skipped: legacy skipped edge count.
• skipped_items: graph parts not queued, including target-filtered nodes/edges and graph parts with existing asset IDs.
• reverse_free: reverse edges that cost 0 credits because they reuse a forward transition.
• already_complete: nodes and edges whose assigned assets are already completed.
• estimated_cost: cost calculated before dispatch.
• actual_cost: credits deducted for this request.
• would_charge_credits: dry-run estimate for the credits a real request would deduct.

Each generated job follows the same lifecycle as a regular animation job - you can poll individual jobs or read the status field on the canvas detail response to track overall progress.

Edge Classification

Not all edges cost the same. The endpoint classifies each edge before generation:

Cost Calculation

Only loops and forward transitions cost credits. The formula is:

(loops + forwards) x 5 x duration

For example, a canvas with 4 loop edges and 3 forward edges at 4 seconds each:

Paid edges: 4 loops + 3 forwards = 7
Cost per edge: 5 credits/sec x 4 sec = 20 credits
Total: 7 x 20 = 140 credits

Reverse edges (auto): 3 (one per forward) = 0 credits
Any State edges: skipped = 0 credits

The response includes estimated_cost, actual_cost, and legacy total_cost fields so you know the exact cost. If you do not have enough credits, the request returns a 402 error with the required amount.

This endpoint returns 200 OK with the list of queued jobs - generation runs asynchronously.

Auto-Reverse

When a forward transition completes (e.g. Idle to Waving), the reverse transition (Waving to Idle) is automatically triggered at 0 credits. You do not need to request it separately. The reverse job appears in the canvas status response alongside the forward jobs.

If a forward edge already has a matching reverse edge in the canvas, the auto-reverse fills in the reverse edge video. If no reverse edge exists, one is created automatically.

Poll Progress

After kicking off generation, fetch the canvas and read the status field to track overall progress:

Before retrying, inspect status.failed_nodes and status.failed_edges. Each entry includes the failed part, its job ID, and a customer-safe error message. A retry is a new paid attempt and should require approval. status.nodes.pending includes failed nodes for backward compatibility; status.nodes.failed identifies the terminal subset.

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

# Response:
# {
#   "data": {
#     "id": "abc-123",
#     "graph": { ... },
#     "status": {
#       "nodes": { "total": 4, "completed": 4, "pending": 0, "failed": 0 },
#       "edges": { "total": 14, "completed": 10, "pending": 3, "failed": 1 },
#       "ready": false,
#       "failed_nodes": [],
#       "failed_edges": []
#     }
#   }
# }

Regenerate a Single Edge

To re-run one edge without re-dispatching the whole canvas, use the per-edge endpoint:

curl -X POST https://api.masko.ai/v1/collections/COLLECTION_ID/canvases/CANVAS_ID/edges/EDGE_ID/generate \
  -H "Authorization: Bearer masko_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "duration": 4
  }'

The endpoint returns 202 Accepted and a job_id. Only non-reverse edges can be dispatched individually. Poll the job as usual.

Use this when one edge failed or you updated the edge prompt and want to regenerate it without spending credits on the rest of the canvas.