> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Canvases and generation

> Generate images, video, audio, or text with Aspect MCP, connect canvas nodes, and retrieve completed results.

Aspect MCP can generate a single result in a project or build a canvas of connected generation steps. Use a canvas when you want to keep references, compare results, or iterate on a connected workflow.

For example, ask your connected assistant:

```text theme={null}
In the Campaign project, create a canvas for a product launch.
Generate a 16:9 studio image of a reusable water bottle, then use it
as the first frame of a four-second video with a slow camera push-in.
Wait for each step to finish and return the final video asset.
```

Generation uses workspace credits. See [Credits and Pricing](/docs/workspace-management/credits-and-pricing) for how generation is billed.

The examples below show tool arguments. Replace uppercase ID placeholders with IDs returned by Aspect tools. Find the project with `workspaces_list` and `projects_list`, or follow [Search and organize media](/docs/mcp/search-and-organize).

## Generate a single result

Call `generations_run` with a `project_id` for a result that does not need a canvas:

```json theme={null}
{
  "project_id": "PROJECT_ID",
  "auto_tier": "faster",
  "modality": "image",
  "prompt": "A reusable water bottle on a stone pedestal, studio lighting.",
  "params": { "aspect_ratio": "16:9" }
}
```

For Auto runs without a canvas node, `modality` is required: `image`, `video`, `audio`, or `text`. Omit `canvas_id` and `node_id`.

To use an existing asset as a reference, include `inputs` with an `asset_id` and the input `handle`, such as `image_ref` for a reference image or `first_frame` for the opening frame of a video. Put text instructions in `prompt`; direct inputs cannot supply generated text or a `source_node_id`.

### Auto or a specific model

Use `auto_tier: "faster"` for quicker, lower-cost model choices, or `auto_tier: "better"` when quality is the priority. Auto chooses a model that can use the inputs and requested parameters. If needed, it also considers the other tier's models. Parameter values the selected model does not offer are adjusted to supported values; the returned run records the actual `model_id` and `params`.

Pass only the settings you need to control. New Auto video nodes and one-off Auto video runs default to a four-second duration request, adjusted to the selected model's supported durations. Auto video `resolution` uses `low` or `high`; Auto image resolution uses `1K`, `2K`, or `4K`. Auto controls model effort through its preset.

For a specific model, call `generations_models_list` and use a returned `model_id` instead of `auto_tier`. The catalog includes `param_schema`, `input_handles`, input limits, and `auto_presets`. Use the model's supported settings and inputs. Supply exactly one of `model_id` or `auto_tier`; `modality` is only for Auto runs without a canvas node.

## Wait for the result

`generations_run` returns a `runs` list as soon as work is accepted. Read each run's `id`, then call `generations_run_wait`:

```json theme={null}
{
  "run_ids": ["RUN_ID"],
  "timeout_seconds": 50
}
```

A wait call accepts up to 10 run IDs and a timeout from 1 to 50 seconds. If `finished` is `false`, call it again with the same IDs. A timeout means work is still in progress; it is not a reason to submit another generation.

When `finished` is `true`, inspect each run:

| Run result | What to use |
| - | - |
| `state: "completed"` with `output_asset_id` | The generated image, video, or audio asset |
| `state: "completed"` with `output_text` | The generated text |
| `state: "failed"` | The run's `error` message |

`finished: true` means every run has completed or failed, so it does not by itself mean success. Use `generations_run_get` with a `run_id` for a one-off status check.

## Build a connected canvas

Use `canvases_list` to find a project's canvases, or create one with `canvases_create`:

```json theme={null}
{
  "canvases": [
    { "project_id": "PROJECT_ID", "name": "Product launch" }
  ]
}
```

Use the new canvas's `id` from the returned `canvases` list as `canvas_id`, then read `canvas_content_get` before adding to or changing it. The snapshot includes nodes, connections, positions, properties, and summaries of active and pending generation runs.

### Add nodes and connections together

Call `canvas_nodes_create` to create the image and video nodes in one call. Temporary `key` values let the same call connect new nodes before their IDs are known:

```json theme={null}
{
  "canvas_id": "CANVAS_ID",
  "nodes": [
    {
      "key": "product-image",
      "node_type": "image_gen",
      "title": "Product image",
      "position_x": 0,
      "position_y": 0,
      "properties": {
        "prompt": "A reusable water bottle on a stone pedestal, studio lighting.",
        "auto_tier": "faster",
        "params": { "aspect_ratio": "16:9" }
      }
    },
    {
      "key": "product-video",
      "node_type": "video_gen",
      "title": "Product video",
      "position_x": 420,
      "position_y": 0,
      "properties": {
        "prompt": "Slow camera push-in. Keep the bottle and lighting consistent.",
        "auto_tier": "faster",
        "params": { "aspect_ratio": "16:9", "duration_seconds": 4 }
      }
    }
  ],
  "edges": [
    {
      "source_key": "product-image",
      "target_key": "product-video",
      "frame_slot": "first_frame"
    }
  ]
}
```

The response maps each temporary key to its `node_id` in `nodes`. Check `failures` and `edge_failures`, and confirm the connections before running dependent nodes. For existing nodes, use `source_node_id` or `target_node_id` instead of a temporary key. Use `canvas_edges_create` to connect nodes in a later call.

Every new node needs a title except an `asset` node, which displays its asset's name. Omit `width` and `height` to use the standard node size; generation nodes follow their aspect ratio. Place new nodes beside the existing work so the graph stays readable.

### Run steps in dependency order

Creating or connecting a node does not start a generation. First call `generations_run` for the image node, using the ID returned for `product-image`:

```json theme={null}
{
  "canvas_id": "CANVAS_ID",
  "node_id": "IMAGE_NODE_ID",
  "auto_tier": "faster",
  "prompt": "A reusable water bottle on a stone pedestal, studio lighting."
}
```

Call `generations_run_wait` until the image completes. Then call `generations_run` for the video node with its stored prompt and model choice, and wait for that run too. Each submit runs the selected node; it does not execute the whole graph.

For canvas runs, pass both `canvas_id` and `node_id`. The project and inputs come from the canvas, so omit `modality` and explicit `inputs`. Pass the node's stored prompt and either its `model_id` or its `auto_tier`. An Auto node's stored parameters apply automatically; any supplied `params` override matching stored settings for that run. For a named model, pass the node's supported parameters explicitly.

## Use references and other node types

| Node type | Purpose |
| - | - |
| `asset` | Reference an existing library asset using `properties.asset_id` |
| `image_gen`, `video_gen`, `audio_gen` | Generate media from a prompt and compatible connected inputs |
| `text_gen` | Generate text that can become prompt context for downstream nodes |
| `text` | Keep standalone notes; these nodes cannot be connected |
| `upscale` | Upscale one image or video input with a matching named upscale model; Auto is not supported |
| `group` | Arrange related nodes inside a titled container; groups do not accept connections |

A connected generation node contributes its displayed completed output. Connecting a `text_gen` node adds its generated text ahead of the target's own prompt. Sources must be ready before the target runs; an unfinished generation or unavailable input is not silently omitted.

For an image feeding an Auto video node, set `frame_slot: "first_frame"` or `frame_slot: "last_frame"` when it should be an endpoint frame. Without `frame_slot`, Auto treats the image as a reference. A last frame also requires a first frame. Connections must fit the target's supported input types and limits; some models cannot combine reference images and endpoint frames.

Input order follows source nodes from top to bottom. Moving source nodes can therefore change the order in which the target receives them.

## Iterate on a result

Read the current canvas before editing it. To preserve an existing result, add a downstream generation node connected to it and describe the change you want, such as a new background or lighting treatment.

Use `canvas_nodes_update` to change a node's prompt, model choice, parameters, position, or title. Its `properties` update merges top-level keys; a `null` value removes a key. A supplied `params` object replaces that property's previous value, so include any settings you want to keep. For example, switching a named-model node back to Auto requires removing `model_id` and setting `auto_tier`.

You can also set `active_run_id` to select which completed run the node displays and feeds downstream. To read full generated text, use `generations_run_get`; the canvas snapshot includes only the first 500 characters of that text.

## Find and download generated media

For a completed media run, call `assets_get` with its `output_asset_id` in `asset_ids` to retrieve the asset's name, project, and path. Text generations return `output_text` on the run instead of creating a media asset.

One-off media outputs are saved in the project's **Aspect Stash** folder. Canvas media outputs are saved in a folder for that canvas inside Aspect Stash. These folders are created when needed; `projects_get` exposes the stash as `system_directory_id` once it exists. Use the returned asset path rather than constructing a folder name yourself.

Use the [Aspect CLI](/docs/cli/downloads) or a mounted project to bring a generated file onto your computer. If the CLI is unavailable on the machine that needs the file, `assets_download_url_get` returns a temporary signed URL for an `asset_id`, with `variant` set to `original`, `stream_proxy`, or `preview`. The default is `original`; `preview` is a thumbnail. Download access is required, and the link expires at `url_expires_at`.

See [MCP troubleshooting](/docs/mcp/troubleshooting) for rejected inputs, unfinished runs, and expired download links.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.