Core Concepts

This page covers the fundamental concepts you need to understand when working with Node Banana.

The Canvas

The canvas is your workspace — an infinite 2D area where you build workflows. You can:

• Pan — Click and drag on empty space, or use scroll wheel
• Zoom — Pinch to zoom, or use Cmd/Ctrl + scroll
• Select — Click nodes, or drag a selection box
• Multi-select — Hold Shift while clicking to select multiple nodes

A minimap in the corner shows your current viewport position and provides quick navigation.

Customizable Canvas Navigation

You can customize how you interact with the canvas to match your preferred workflow. Open Project Settings (gear icon in the header) and go to the Canvas tab to configure:

Settings are saved to localStorage and persist across sessions.

Nodes

Nodes are the building blocks of your workflow. Each node performs a specific function:

See the Nodes Reference for detailed information on each node type.

Node Anatomy

Every node has:

• Title bar — Shows the node type (click to edit the name)
• Input handles — Connection points on the left
• Output handles — Connection points on the right
• Body — Node-specific controls and content
• Resize handle — Bottom-right corner for resizing

Edges (Connections)

Edges are the lines that connect nodes. Data flows through edges from outputs to inputs.

Creating Connections

1. Click and hold on an output handle
2. Drag to a compatible input handle
3. Release to create the connection

Connection Rules

• Text → Text: Prompt outputs connect to text inputs
• Image → Image: Image outputs connect to image inputs
• Video → Video: Video outputs connect to video inputs
• Audio → Audio: Audio outputs connect to audio inputs
• 3D Model → 3D Model: 3D outputs connect to 3D inputs (e.g., Generate 3D → 3D Viewer)
• Ease Curve → Ease Curve: Easing configurations can be passed between Ease Curve nodes
• Multiple connections: Image and video inputs can receive multiple connections; text inputs accept one
• Type safety: You cannot connect incompatible types (e.g., text to image, audio to video)

Edge States

• Normal — Gray line, data flows through
• Paused — Dashed line, execution stops here
• Error — Red line, indicates a problem

Click an edge to toggle pause state. Right-click to delete.

Handle Types

Handles are the connection points on nodes. Node Banana has six handle types:

Image Handles

Used for visual content. Image data flows as base64-encoded data URLs.

• Found on: Image Input, Annotation, Generate Image, Split Grid, 3D Viewer (output), Output
• Color: Green
• Accepts: PNG, JPG, WebP images

Audio Handles

Used for audio content. Audio data flows as file references or data URLs.

• Found on: Audio Input (output), Video Stitch (input)
• Purpose: Add audio tracks to videos
• Accepts: MP3, WAV, and other browser-supported formats

Video Handles

Used for video content. Video data flows as URLs or base64-encoded data.

• Found on: Generate Video, Video Stitch, Ease Curve, Output
• Accepts: Various video formats (MP4, WebM, etc.)

Text Handles

Used for string content like prompts and generated text.

• Found on: Prompt (input and output), LLM Generate (input and output), Generate Image (input), Generate Video (input), Generate 3D (input)
• Color: Blue
• Accepts: Any text string

3D Model Handles

Used for 3D model content. 3D models flow as GLB files.

• Found on: Generate 3D (output), 3D Viewer (input)
• Color: Orange
• Accepts: GLB 3D model files
• Connection validation: 3D outputs can only connect to 3D inputs

Ease Curve Handles

Used for passing easing configuration between Ease Curve nodes.

• Found on: Ease Curve (input and output)
• Purpose: Chain multiple easing effects together
• Data: Cubic bezier control points and preset configurations

Reference Handles

Used for organizational purposes, primarily with Split Grid.

• Found on: Split Grid (outputs)
• Purpose: Visual organization, not data transfer

Workflow Execution

When you run a workflow, Node Banana executes nodes in dependency order using topological sorting. Independent nodes at the same dependency level execute in parallel for improved performance.

Execution Order

1. Nodes with no dependencies run first (source nodes)
2. Independent nodes at the same level execute in parallel
3. Downstream nodes run after their inputs are ready
4. The workflow completes when all nodes have executed

Parallel Execution

Node Banana automatically identifies nodes that can run simultaneously:

• Level-based grouping: Nodes are grouped by dependency depth
• Parallel execution: All nodes in a level execute concurrently
• Performance gains: Workflows with multiple independent generation nodes complete significantly faster

Example: A workflow with 3 independent image generation nodes (each taking 20s) completes in ~20s instead of 60s.

The floating action bar shows parallel execution status:

• "Running..." (no nodes)
• "Running {NodeLabel}..." (single node)
• "Running N nodes..." (multiple nodes in parallel)

Running Workflows

• Cmd/Ctrl + Enter — Run entire workflow
• Run button — Click in header to run all
• Run selected — Select nodes and choose "Run N selected nodes" from the Run dropdown
• Node play button — Run from a specific node
• Regenerate — Re-run a single node with same inputs

Execute Selected Nodes

When you select one or more nodes, the Run dropdown in the floating action bar shows the option to run only the selected nodes:

• Execution respects dependency order (topological sort)
• Upstream dependencies of selected nodes execute first
• Downstream nodes that depend on selected nodes also execute
• Supports abort/cancellation mid-execution

This is useful for testing specific parts of a workflow without running everything.

Execution States

Nodes show their current state:

• Idle — Ready to run
• Running — Currently executing (shows spinner)
• Complete — Finished successfully
• Error — Something went wrong (shows error message)

Groups

Groups let you organize related nodes together.

Creating Groups

1. Select multiple nodes
2. Right-click and select "Create Group"
3. Name your group

Group Features

• Visual boundary — Groups have a colored background
• Move together — Dragging the group moves all contained nodes
• Lock groups — Locked groups are skipped during execution

Keyboard Shortcuts

Cost Tracking

Node Banana tracks API costs for image and text generation.

How Costs Work

• Each generation node shows estimated cost before running
• Actual costs are tracked after generation
• Total workflow cost displays in the header
• Costs persist between sessions

Pricing (Approximate)

See Models & Pricing for detailed pricing information.

Auto-Save

Node Banana automatically saves your work:

• Interval — Every 90 seconds when enabled
• Location — Configured in project settings
• Format — JSON workflow files
• Image storage — Workflows can store images as external files (default) or embedded base64 data. The useExternalImageStorage setting persists in the workflow configuration.

The header shows save status and last save time.

Save Directory Changes

When you save a workflow to a different directory:

• Image references are automatically cleared to prevent invalid paths
• A new workflow ID is generated to avoid localStorage conflicts
• Images are re-saved to the new location
• Image history IDs are preserved during the migration

This ensures your workflow remains self-contained and portable across different project directories.