Run a canvas workflow

Save the fixed images first

Anything that stays the same on every run should be a durable node before the workflow exists. See Save a generated image.

{
  "name": "save_image_to_canvas",
  "arguments": {
    "imageUrl": "https://example.com/product-hero.png",
    "destination": "canvas:abc123:product-shots",
    "title": "Product hero — locked",
    "idempotencyKey": "product-hero-2026-08-04-01"
  }
}

Keep the returned handle — say node:img8q4 — and the canvas handle.

Getting the order wrong here is the mistake that costs the most later. A workflow built without pinned defaults makes every single run re-supply the product shot.

Create the workflow

{
  "name": "create_canvas_workflow",
  "arguments": {
    "destination": "canvas:abc123:product-shots",
    "name": "Product on seasonal backgrounds",
    "description": "Same product shot, new background per run.",
    "category": "Product Visualization",
    "tags": ["product", "seasonal"],
    "inputs": [
      {
        "key": "product",
        "label": "Product shot",
        "description": "Locked. Do not substitute.",
        "type": "image",
        "sourceNodeId": "node:img8q4",
        "useAsDefault": true
      },
      {
        "key": "background",
        "label": "Background direction",
        "description": "Surface, colour, and light for this run.",
        "type": "text",
        "value": "matte cream, soft window light",
        "useAsDefault": false
      }
    ],
    "outputs": [
      {
        "key": "hero",
        "label": "Hero image",
        "type": "image",
        "prompt": "Place the exact connected product on the described background. Preserve the product precisely — do not substitute, restyle, or redraw it.",
        "inputKeys": ["product", "background"],
        "size": "1024x1024"
      }
    ],
    "idempotencyKey": "seasonal-workflow-2026-08-04-01"
  }
}

Three things to notice:

• useAsDefault: true on product is what lets later runs omit it entirely.
• Image inputs use sourceNodeId, never value. The schema is strict — an image input carrying value is rejected outright.
• The output prompt says “preserve the exact connected product”. Every product-variant workflow should say this explicitly; otherwise the model treats the product as a suggestion.

category must be one of Brand & Visual Design, Product Visualization, Marketing & Ads, or Content Package. Limits: 1–16 inputs, 1–8 outputs, and every inputKeys entry must name a key you actually declared.

Check: the response gives you a workflowNodeId and a browser url.

Stop

Building is done. Unless the user asked to run it in this message, the turn ends here:

Created “Product on seasonal backgrounds” as node:wf7k2m on canvas:abc123:product-shots. The product shot is pinned as a default, so a run only needs a background direction. I have not run it — running generates an image and uses your provider. Want me to?

Get explicit approval

The user must ask to run it, in the current message. Not “build me a workflow”, not an approval from three turns ago, not a node labelled “hero image” sitting empty.

Name what it will do before asking:

This will generate 1 image using your connected provider. Run it?

Run with only what changes

{
  "name": "run_canvas_workflow",
  "arguments": {
    "destination": "canvas:abc123:product-shots",
    "workflowNodeId": "node:wf7k2m",
    "inputs": { "background": "matte terracotta, low autumn sun, long soft shadows" },
    "idempotencyKey": "terracotta-run-2026-08-04-01",
    "waitSeconds": 45
  }
}

product is absent because it is a stored default. inputs accepts up to 16 entries, each value 1–8,000 characters, keyed by stable input key, exact portNodeId, or input label. Image values must be node: or asset: handles.

destination must be the canvas the workflow card lives on.

Check the response for status. One of two things happened.

If it finished

You get the completed run with its outputs. Image outputs are resolved to their canvas nodes and come back with previews the model can inspect. Note the output node handles.

Skip to the last step.

If it timed out

You get the queued run back, with its status, the destination, and the workflowNodeId.

Poll instead:

{ "name": "get_canvas_workflow_run", "arguments": { "runId": "run:9f3a2b" } }

Polling is free and needs only canvas:read and job:manage. Call it again while the status is queued or running, with a sensible gap between calls.

waitSeconds accepts 1–50 and defaults to 45. Raising it does not make the work faster; it only changes how long the tool blocks before handing you a handle.

Verify the result is durable

A run reporting success is not the same as durable canvas content. Confirm the output landed:

{ "name": "canvas_get", "arguments": { "canvasId": "canvas:abc123:product-shots" } }

Check: the output node exists, is of type image, and carries server-owned media rather than being an empty placeholder. Report what the server actually returned — do not describe a temporary handle as a finished canvas output.

Report and link

{ "name": "open_canvas", "arguments": { "canvasId": "canvas:abc123:product-shots" } }

Run run:9f3a2b succeeded. Output image is node:out5y6 on canvas:abc123:product-shots. Review it here: https://app.gavana.ai/…