workspaces_list and projects_list, or follow Search and organize media.
Generate a single result
Callgenerations_run with a project_id for a result that does not need a canvas:
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
Useauto_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:
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:
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
Usecanvases_list to find a project’s canvases, or create one with canvases_create:
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
Callcanvas_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:
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 callgenerations_run for the image node, using the ID returned for product-image:
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
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. Usecanvas_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, callassets_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 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 for rejected inputs, unfinished runs, and expired download links.