> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp/recipes/canvas.md).

# Put results on a canvas

Lay out FLORA MCP results on a project canvas from your agent: arrange generations into a grid, add and wire image, video and text nodes, and group work into fields.

Everything your agent generates with [FLORA MCP](https://flora.ai/mcp) already lands on a project canvas as nodes. This recipe covers the next step: laying them out as a grid, building a small graph of wired nodes, and sorting work into named fields. Use it after [Generate an image or video](https://docs.flora.ai/mcp/recipes/generate.md) or [Batch-generate 20 to 500 assets](https://docs.flora.ai/mcp/recipes/batch.md), or whenever you want the canvas to read like a board.

**Works in:** Claude · Claude Code · ChatGPT · Codex · Cursor

**You need:** a connected client and a project. Arranging, adding and organizing nodes cost nothing; only running generation nodes does (about $0.07 per image with Nano Banana 2).

**Use when:** results need a layout, or you want to set up a chain of nodes (reference → image → video) that runs together.

**Don't use when:** you just need the output URLs; generation already put the nodes on the canvas.

## Ask your agent

> In my FLORA project "Fall PDP", make 8 hero images of our walnut cutting board and lay them out in a 4-column grid. Show me the cost first and wait for my OK.

<a href="https://claude.ai/new?q=In%20my%20FLORA%20project%20%22Fall%20PDP%22%2C%20make%208%20hero%20images%20of%20our%20walnut%20cutting%20board%20and%20lay%20them%20out%20in%20a%204-column%20grid.%20Show%20me%20the%20cost%20first%20and%20wait%20for%20my%20OK." class="button primary">Open in Claude</a> <a href="https://chatgpt.com/?q=In%20my%20FLORA%20project%20%22Fall%20PDP%22%2C%20make%208%20hero%20images%20of%20our%20walnut%20cutting%20board%20and%20lay%20them%20out%20in%20a%204-column%20grid.%20Show%20me%20the%20cost%20first%20and%20wait%20for%20my%20OK." class="button secondary">Open in ChatGPT</a>

## What the agent does

1. Generates the images with `flora_create_generations` (see [generate](https://docs.flora.ai/mcp/recipes/generate.md)). Each response entry carries the new node's `node_id`.
2. Arranges those nodes in one `flora_arrange_canvas` call.
3. Optionally adds wired nodes with `flora_add_to_canvas` and runs them with `flora_run_canvas_nodes`.
4. Optionally sorts work into named fields with `flora_organize_canvas_fields`.

### Arrange a grid

Pass the node IDs in the order you want them placed, plus a `layout`. Use the `node_id`s saved from `flora_create_generations`. If they're no longer in the conversation, read `flora_get_canvas` and pick the results by node type (`image`), `prompt`, `model` and a completed status; ask the user if that still leaves doubt.

```json
{
  "project_id": "prj_abc",
  "node_ids": ["n12", "n13", "n14", "n15", "n16", "n17", "n18", "n19"],
  "layout": { "mode": "grid", "columns": 4, "gap": 64 }
}
```

* `mode` is `row`, `column` or `grid`. `columns` applies to grids only and defaults to the square root of the count, rounded up. `gap` defaults to 64 canvas units. Send `node_ids` without `layout` to tidy just those nodes instead of gridding them.
* IDs can be short IDs (`n12`) or node UUIDs from `flora_get_canvas`, the `node_id` values `flora_create_generations` returned, or an uploaded file's node: `mcp_upload_…` when it was uploaded with `project_id`, or the `api_asset_…` ID `flora_attach_asset` returned. Never pass a bare asset ID (`asset_…`) or an ID you predicted; one unknown ID rejects the whole call and nothing moves.
* Leave out `layout.origin` and FLORA keeps the block where the set already is, shifted clear of other work. Pass an origin only to place it somewhere specific.
* `layout.origin` is the **painted top-left corner** of the block (where the first box starts), not a node's position. Node positions in `flora_get_canvas` are anchors at the **top-center** of each box (groups anchor top-left). So to start a block where an existing node sits, use `origin.x = anchor x − width / 2` and `origin.y = anchor y`: a 384-wide node anchored at `x: 0` starts painting at `x: -192`.
* To line a new row up under an existing grid, set `gap` to the distance between the existing column anchors minus the node width (not the default 64), and set `origin.y` to continue the existing row spacing. An explicit origin can collide with other work; check `overlaps` in the response.

The response is `{ arranged, moved, overlaps, bounds, revision }`. An empty `overlaps` is the only clean result. `bounds` is the block's box, so the next batch can go below it at `origin.y = bounds.y + bounds.height + gap`.

To tidy the whole canvas instead, send `all: true` and nothing else. That runs Tidy, the editor's own auto-layout, on every node: it follows the edges (each source sits to the left of the nodes it feeds) and keeps group members inside their frames, instead of making a grid. `overlaps` always comes back empty. Do this only when you ask for it, because it moves work you placed by hand:

```json
{
  "project_id": "prj_abc",
  "all": true
}
```

{% hint style="warning" %}
`flora_arrange_canvas` takes `node_ids` (with an optional `layout`) **or** `all: true` on its own. Never both, and never `all` with `layout`. A call with neither is rejected too.
{% endhint %}

### Add and wire nodes

`flora_add_to_canvas` creates nodes and edges in one call. Each `add` entry has a `type`; give it a `ref` when an edge in the same call points at it. Each `connect` entry wires two nodes by short ID or `ref`. Edges feed one node's output into the next by media type unless you name a target input with `in`.

```json
{
  "project_id": "prj_abc",
  "idempotency_key": "fall-pdp-board-1",
  "add": [
    {
      "ref": "ref_photo",
      "type": "static_image",
      "content_url": "https://media.flora.ai/…/board-front.png",
      "label": "Product reference"
    },
    {
      "ref": "copy",
      "type": "text",
      "prompt": "Write a one-line scene description for a cozy autumn kitchen product shot of a walnut cutting board"
    },
    {
      "ref": "hero",
      "type": "image",
      "prompt": "The walnut cutting board from the reference on a rustic kitchen counter, warm autumn light, 4:5",
      "model": "i2i-gemini-3.1-flash-image",
      "params": { "aspect_ratio": "4:5" }
    },
    {
      "ref": "clip",
      "type": "video",
      "prompt": "Slow orbit around the cutting board, warm light, steam from a mug in the background",
      "model": "i2v-kling-v3-pro",
      "params": { "duration": "5" }
    },
    {
      "type": "notes",
      "text": "Fall PDP board. Hero feeds the video. Approve the hero before running the clip."
    }
  ],
  "connect": [
    { "from": "ref_photo", "to": "hero" },
    { "from": "hero", "to": "clip" }
  ]
}
```

Node types you'll use most:

| `type`                    | What it is                                                 | Takes                                                 |
| ------------------------- | ---------------------------------------------------------- | ----------------------------------------------------- |
| `static_image`            | An existing image, placed as is                            | `content_url` (HTTPS)                                 |
| `image`, `video`, `audio` | A generation node (or, with `content_url`, existing media) | `prompt`, `model`, `params`; or `content_url` instead |
| `text`                    | A text generation node (its prompt runs a text model)      | `prompt`, `model`, `params`                           |
| `notes`                   | A note for people; never runs                              | `text` (up to 20,000 characters), `size`, `fit_text`  |
| `group`                   | A frame other nodes can sit in                             | members join with `group`                             |

Rules worth knowing:

* `prompt`, `model` and `params` configure a generation node; `content_url` places existing media instead and can't be combined with them. Media inputs such as `image_url` come from edges, not `params`.
* `params` are checked against the model's schema; an invalid value rejects the whole call. Leave out `model` to use the default for that node type.
* 3D nodes can't be created here. Generate 3D with `flora_create_generations`.
* Leave out `position` and FLORA places new nodes below existing work.
* Reuse the same `idempotency_key` after a timeout so a retry can't create duplicates.

The response's `created` map gives each `ref` its real short ID and UUID, for example `"hero": { "id": "n21", "node_id": "…" }`. Use those for every later call, never your refs. Warnings in the response mean part of the request was skipped (a duplicate edge, for example).

{% hint style="danger" %}
`flora_add_to_canvas` takes JSON `add` and `connect` arrays only. A Mermaid diagram or any other text graph is rejected. Describe each node and edge as JSON.
{% endhint %}

### Run what you added

Adding a node never runs it. After you approve the cost, `flora_run_canvas_nodes` starts the nodes by short ID. Connected nodes run in dependency order, so a whole chain starts in one call (up to 50 nodes):

```json
{
  "project_id": "prj_abc",
  "node_ids": ["n20", "n21", "n22"]
}
```

It spends money immediately with no confirmation step, so the agent quotes first (see [cost and limits](https://docs.flora.ai/mcp/cost-and-limits.md)). Each entry in `runs` is `started` with a `run_id` to poll with `flora_list_generations`, or `skipped` with a `reason`. Skipped nodes aren't charged.

### Sort work into fields

`flora_organize_canvas_fields` moves existing nodes into named fields (frames), creating a field if no top-level field has that label, and grids each one. It never recreates nodes or changes their content or edges:

```json
{
  "project_id": "prj_abc",
  "fields": [
    { "label": "Concepts", "node_ids": ["n12", "n13", "n14", "n15"] },
    { "label": "Finals", "node_ids": ["n16", "n18"] }
  ]
}
```

Up to 50 fields and 200 nodes per call. It takes no coordinates. If it's interrupted, read the canvas with `flora_get_canvas` and run it again with the same labels and IDs; it reuses the frames it already made. If your connection doesn't list this tool, create an empty `group` node with `flora_add_to_canvas`, then move nodes into it with `flora_update_canvas_nodes` and `group`.

## Check it worked

* `flora_arrange_canvas` returns an empty `overlaps` array.
* `flora_get_canvas` shows each node's `position`, `group` and edges as you expect, and a new `revision`.
* The canvas at `canvas_url` reads as the grid or board you asked for.

## If it fails

| Symptom                              | Cause                                                                                         | Fix                                                                                                        |
| ------------------------------------ | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `flora_arrange_canvas` rejected      | Both `node_ids` and `all` were sent, `all` with `layout`, or neither                          | Send `node_ids` (+ `layout`) or `all: true` alone.                                                         |
| Rejected with an unknown ID          | A ref, a predicted ID or a bare `asset_…` ID was passed                                       | Use IDs from `flora_get_canvas`, the `created` map, or an upload's node (`mcp_upload_…` or `api_asset_…`). |
| `overlaps` is not empty              | The block collides with work outside it                                                       | Run again without `origin`, or with an origin clear of other work.                                         |
| `flora_add_to_canvas` returns 400    | The request was Mermaid or text instead of JSON arrays, or `params` failed the model's schema | Send `add` and `connect` as JSON, with `params` names from `flora_list_models`.                            |
| Node added but nothing happened      | Adding doesn't run a node                                                                     | Run it with `flora_run_canvas_nodes` and its short ID.                                                     |
| `skipped` with `node_not_found`      | A `ref` was passed instead of a short ID                                                      | Use the `id` from the `created` map.                                                                       |
| `skipped` with `node_not_executable` | The node is static text: it passes its text downstream and never generates                    | Run the generation nodes it feeds instead.                                                                 |

Every argument is in the [canvas tools reference](https://docs.flora.ai/mcp/tools/canvas.md#flora_arrange_canvas).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/mcp/recipes/canvas.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
