LLM API Documentation

ImageNodes LLM API

This page documents the ImageNodes API endpoints designed for Large Language Model (LLM) integration. These endpoints allow AI systems to programmatically discover available image processing operations, estimate costs, and execute pipelines dynamically.

Overview

ImageNodes provides four LLM-focused endpoints:

Endpoint Method Description
/api/v1/schema/nodes GET Get schemas for all available node types
/api/v1/pipeline/validate POST Validate a pipeline without executing it
/api/v1/pipeline/estimate-cost POST Estimate pipeline execution cost
/api/v1/pipeline/evaluate POST Execute a pipeline from JSON

Requirements:

  • Valid API key (header: X-API-KEY)
  • Paid subscription tier

Authentication

All requests require an API key in the header:

X-API-KEY: your_api_key_here

Base URL

https://imagenodes.com/api/v1

Get Node Schemas

GET /schema/nodes

Returns complete schemas for all available node types, including inputs, outputs, parameters, and example use cases. This is the primary discovery endpoint for LLMs to understand what operations are available.

Response Structure

{
  "error": false,
  "message": "Available node types",
  "data": [
    {
      "type": "NodeType.solidcanvas",
      "display_name": "Solid Color Canvas",
      "description": "Creates a solid color canvas of specified dimensions",
      "category": "source",
      "inputs": [],
      "outputs": [
        {
          "name": "output",
          "type": "Image",
          "required": false,
          "description": "A solid color image"
        }
      ],
      "parameters": [
        {
          "name": "params_size",
          "type": "size",
          "default": {"height": 600, "width": 800},
          "description": "Canvas dimensions in pixels"
        },
        {
          "name": "params_colour",
          "type": "color",
          "default": "#FFFFFF",
          "description": "Fill color for the canvas"
        }
      ],
      "cost": 0,
      "examples": [
        "Create a white background for image composition",
        "Generate a colored backdrop for text overlays"
      ]
    }
  ]
}

Node Categories

  • source - Create or load images (URL import, asset library, solid canvas, gradient, noise generator)
  • transform - Modify images (resize, rotate, blur, edge detection, color adjustments, smart crop)
  • draw - Draw on images (text, paragraphs, shapes)
  • combine - Combine images (merge, insert into, composite, mask)
  • output - Output nodes (final output)
  • utility - Helper nodes (image attributes, size calculations, API parameters, nested pipelines)

Parameter Types Reference

IMPORTANT: Using incorrect parameter formats is the most common cause of pipeline errors. Follow these formats exactly.

Type JSON Format Example Constraints
number {"num": n} {"num": 1.5} Varies by parameter
text {"string": "..."} {"string": "Hello"} -
color {"string": "#RRGGBBAA"} {"string": "#FF5733FF"} Must be 8-digit hex (RGBA)
size {"string": "W x H"} {"string": "800 x 600"} Positive integers, space around x
position {"string": "X x Y"} {"string": "50 x 100"} Pixel offset from top-left
angle {"num": n} {"num": 45} -180 to 180 (not 0-360)
boolean {"num": 0\|1} {"num": 1} 0 = false, 1 = true

Common Mistakes

  1. Node IDs: Using underscores (card_bg) instead of camelCase (cardBg). Node IDs cannot contain underscores.
  2. Colors: Using 6-digit hex (#FF5733) instead of 8-digit (#FF5733FF). Always include alpha channel.
  3. Angles: Using 0-360 range. The valid range is -180 to 180. For a full circle, use start=-180, end=180.
  4. Booleans: Using {"bool": true} instead of {"num": 1}.
  5. Size/Position: Missing spaces around x or using named positions like “center” where numeric values are expected.

Pipeline JSON Structure

Pipelines use the following structure:

{
  "pipeline": {
    "id": "12345678-1234-1234-1234-123456789abc",
    "nodes": {
      "node_id": {
        "id": "node_id",
        "name": "Display Name",
        "node_type": "NodeType.solidcanvas",
        "position_x": 0,
        "position_y": 0
      }
    },
    "values": {
      "node_id_params_size": {"string": "800 x 400"},
      "node_id_params_colour": {"string": "#3498dbFF"}
    },
    "connectionMapFwd": {
      "source_output": ["target_input"]
    },
    "connectionMapRev": {
      "target_input": "source_output"
    }
  }
}

Key Fields

Field Description
id Pipeline UUID (must be valid UUID format)
nodes Map of node ID to node definition
values Map of parameter keys to values
connectionMapFwd Forward connections: output_connector → [input_connectors]
connectionMapRev Reverse connections: input_connector → output_connector

Node Definition

{
  "id": "canvas",
  "name": "My Canvas",
  "node_type": "NodeType.solidcanvas",
  "position_x": 0,
  "position_y": 0
}

Node ID Requirements

IMPORTANT: Node IDs have strict formatting requirements:

Requirement Valid Examples Invalid Examples
No underscores canvas, myText, gradientBg card_bg, my_text, gradient_bg
camelCase for multi-word titleText, mergeNodes title_text, merge_nodes
Alphanumeric + hyphens OK node1, my-node node_1

Why? Connector IDs use the format {nodeId}_{suffix} (e.g., canvas_output, merge_bg_input). Underscores in node IDs would break connector parsing.

Valid node IDs:

  • canvas
  • myText
  • gradientBg
  • mergeTitle
  • out
  • layer1

Invalid node IDs (will cause validation errors):

  • card_bg → use cardBg
  • merge_title → use mergeTitle
  • gradient_bg → use gradientBg

Connector Naming

  • Output connectors: {nodeId}_output
  • Input connectors: {nodeId}_input (for single input nodes)
  • Named inputs: {nodeId}_{inputName} (e.g., merge_fg_input, merge_bg_input)
  • Composite layers: {nodeId}_layer_N (e.g., composite_layer_0, composite_layer_1)

Value Keys

Format: {nodeId}_{parameterName}

Example: canvas_params_colour for the params_colour parameter of node canvas

Validate Pipeline

POST /pipeline/validate

Validate a pipeline structure without executing it. Returns detailed error information to help fix issues before execution. Recommended: Call this before /pipeline/evaluate to catch errors without consuming credits.

Request Body

Same structure as /pipeline/evaluate (see Pipeline JSON Structure).

Response (Valid)

{
  "error": false,
  "message": "Pipeline is valid",
  "data": {
    "valid": true,
    "errors": null
  }
}

Response (Invalid)

{
  "error": false,
  "message": "Pipeline validation failed: 2 error(s) found",
  "data": {
    "valid": false,
    "errors": [
      {
        "type": "invalid_node_id",
        "node_id": "card_bg",
        "message": "Node ID cannot contain underscores. Use camelCase instead (e.g., 'cardBg' not 'card_bg')"
      },
      {
        "type": "missing_required_input",
        "node_id": "merge",
        "connector": "bg_input",
        "message": "Required input 'bg_input' is not connected"
      }
    ]
  }
}

Validation Error Types

Type Description
invalid_node_id Node ID contains underscores (use camelCase instead)
missing_required_input A required input connector is not connected
cycle_detected Pipeline contains a circular dependency
unknown_node_type Node type is not recognized
invalid_parameter A parameter value is invalid
missing_node A referenced node doesn’t exist
invalid_connection A connection is invalid

Estimate Pipeline Cost

POST /pipeline/estimate-cost

Calculate the credit cost of a pipeline before executing it.

Request Body

{
  "pipeline": {
    "id": "12345678-1234-1234-1234-123456789abc",
    "nodes": {
      "canvas": {
        "id": "canvas",
        "name": "Background",
        "node_type": "NodeType.solidcanvas",
        "position_x": 0,
        "position_y": 0
      },
      "out": {
        "id": "out",
        "name": "Output",
        "node_type": "NodeType.output",
        "position_x": 200,
        "position_y": 0
      }
    },
    "values": {},
    "connectionMapFwd": {
      "canvas_output": ["out_input"]
    },
    "connectionMapRev": {
      "out_input": "canvas_output"
    }
  }
}

Response

{
  "error": false,
  "message": "Cost estimation completed",
  "data": {
    "estimated_cost": 1,
    "node_count": 2,
    "breakdown": {
      "NodeType.output": 0,
      "NodeType.solidcanvas": 0
    },
    "metadata": {
      "note": "Actual cost may vary based on runtime conditions"
    }
  }
}

Evaluate Pipeline

POST /pipeline/evaluate

Execute a pipeline and return the generated image as base64.

Complete Example

This example creates a blue canvas with “Hello LLM!” text:

{
  "pipeline": {
    "id": "12345678-1234-1234-1234-123456789abc",
    "nodes": {
      "canvas": {
        "id": "canvas",
        "name": "Background",
        "node_type": "NodeType.solidcanvas",
        "position_x": 0,
        "position_y": 0
      },
      "text": {
        "id": "text",
        "name": "Title",
        "node_type": "NodeType.text",
        "position_x": 0,
        "position_y": 100
      },
      "merge": {
        "id": "merge",
        "name": "Combine",
        "node_type": "NodeType.merge",
        "position_x": 200,
        "position_y": 50
      },
      "out": {
        "id": "out",
        "name": "Output",
        "node_type": "NodeType.output",
        "position_x": 400,
        "position_y": 50
      }
    },
    "values": {
      "canvas_params_size": {"string": "800 x 400"},
      "canvas_params_colour": {"string": "#2c3e50FF"},
      "text_params_text": {"string": "Hello LLM!"},
      "text_params_colour": {"string": "#ecf0f1FF"},
      "text_params_width": {"num": 800},
      "text_params_font": {"string": "OpenSans"}
    },
    "connectionMapFwd": {
      "canvas_output": ["merge_bg_input"],
      "text_output": ["merge_fg_input"],
      "merge_output": ["out_input"]
    },
    "connectionMapRev": {
      "merge_bg_input": "canvas_output",
      "merge_fg_input": "text_output",
      "out_input": "merge_output"
    }
  }
}

Response (Success)

{
  "error": false,
  "message": "Pipeline evaluated successfully",
  "data": {
    "success": true,
    "output": "iVBORw0KGgo...(base64 PNG data)",
    "cost": 2,
    "metadata": {
      "execution_time_ms": 13,
      "node_count": 4,
      "credits_remaining": 997
    }
  }
}

Response (Error)

{
  "error": false,
  "message": "",
  "data": {
    "success": false,
    "error": "pipelineGraphData is not solvable (may contain cycles or missing required connections)",
    "cost": 0
  }
}

Available Fonts

The text node supports these fonts:

  • OpenSans (default sans-serif)
  • Lora (serif)
  • Inconsolata (monospace)
  • DancingScript (script)
  • Comfortaa (rounded)
  • Raleway (elegant sans)
  • Orbitron (futuristic)
  • Cairo (Arabic support)
  • Jura (geometric)
  • MarkaziText (Arabic serif)
  • NotoSerifDisplay (multilingual serif)

Merge Modes

The merge node’s params parameter accepts these blend modes:

Mode Description
Normal Standard layering (foreground over background)
Multiply Darkens by multiplying colors
Screen Lightens by inverse multiplication
Overlay Combines Multiply and Screen
Darken Keeps darker pixels
Lighten Keeps lighter pixels
ColorDodge Brightens background based on foreground
ColorBurn Darkens background based on foreground
HardLight Intense contrast effect
SoftLight Subtle contrast effect
Difference Subtracts colors
Exclusion Similar to Difference but lower contrast

Example value: {"string": "Overlay"}

Paragraph Alignment

The paragraph node’s params_align parameter accepts either format:

String format (recommended):

Value Alignment
"left" Left-aligned
"center" Center-aligned
"right" Right-aligned

Example: {"string": "center"}

Numeric format (also supported):

Value Alignment
0 Left-aligned
1 Center-aligned
2 Right-aligned

Example: {"num": 1}

InsertInto Position

The InsertInto node’s params_position parameter accepts pixel coordinates:

Format: {"string": "X x Y"} where X and Y are pixel offsets from top-left.

Examples:

  • {"string": "0 x 0"} - Top-left corner
  • {"string": "100 x 50"} - 100px from left, 50px from top
  • {"string": "center"} - Center the foreground (special keyword)

Note: Named positions like “top-left” or “bottom-right” are not supported. Use numeric coordinates.

Composite Positions

The Composite node’s layer_N_position parameters accept either pixel coordinates or keyword positions:

Pixel Format: {"string": "X x Y"} where X and Y are pixel offsets from top-left.

Keyword Positions:

Keyword Description
top-left Align to top-left corner
top-center Align to top edge, centered horizontally
top-right Align to top-right corner
center-left Align to left edge, centered vertically
center Center both horizontally and vertically
center-right Align to right edge, centered vertically
bottom-left Align to bottom-left corner
bottom-center Align to bottom edge, centered horizontally
bottom-right Align to bottom-right corner

Examples:

  • {"string": "0 x 0"} - Position at top-left (pixel coordinates)
  • {"string": "center"} - Center the layer on the base
  • {"string": "top-right"} - Position in top-right corner
  • {"string": "bottom-center"} - Position at bottom, horizontally centered

Note: Layer 0 should typically use "0 x 0" as it serves as the base canvas.

Node Parameter Reference

Complete reference for all node types and their parameters.

Source Nodes

NodeType.solidcanvas

Creates a solid color canvas.

Parameter Type Example Description
params_size size {"string": "800 x 600"} Canvas dimensions
params_colour color {"string": "#3498DBFF"} Fill color (8-digit hex)

NodeType.gradientcanvas

Creates a gradient canvas.

Parameter Type Example Description
params_size size {"string": "800 x 600"} Canvas dimensions
params_colour_start color {"string": "#FF6B6BFF"} Start color
params_colour_end color {"string": "#4ECDC4FF"} End color
params_gradient_angle angle {"num": 45} Gradient direction (-180 to 180)

NodeType.noisegen

Generates Perlin noise texture.

Parameter Type Example Description
params_size size {"string": "400 x 400"} or {"string": "image"} Dimensions or “image” to infer from connected input
params_frequency number {"num": 0.05} Noise frequency (smaller = larger features)

Note: Use "image" for size when connected to a size_input connector to inherit dimensions.

NodeType.start

Loads an image from a URL. This is typically the starting point of a pipeline when processing external images.

Parameter Type Example Description
params text {"string": "https://example.com/image.jpg"} URL of the image to load (http/https)

Output: output (image)

Note: Supports common image formats (JPEG, PNG, GIF, WebP, BMP, TIFF). The URL must be publicly accessible.

NodeType.asset

Loads an image from your asset library. Use this for logos, device frames, and other reusable images stored in your account.

Parameter Type Example Description
params_asset_id text {"string": "550e8400-e29b-41d4-a716-446655440000"} UUID of the asset from your asset library

Output: output (image)

Note: Asset IDs can be found in your ImageNodes dashboard under the Assets section. Assets must be uploaded before they can be used in pipelines.

Drawing Nodes

NodeType.text

Renders single-line text sized to fit width.

Parameter Type Example Description
params_text text {"string": "Hello World"} Text content
params_width number {"num": 800} Maximum width (text scales to fit)
params_font text {"string": "OpenSans"} Font name (see Available Fonts)
params_colour color {"string": "#FFFFFFFF"} Text color

NodeType.paragraph

Renders multi-line text with wrapping.

Parameter Type Example Description
params_text text {"string": "Long text..."} Text content
params_size size {"string": "300 x 200"} Bounding box
params_font text {"string": "Lora"} Font name
params_font_size number {"num": 16} Font size in pixels
params_line_height number {"num": 1.5} Line height multiplier
params_align text or number {"string": "center"} Alignment: “left”, “center”, “right” (or 0, 1, 2)
params_colour color {"string": "#000000FF"} Text color

NodeType.ellipse

Draws an ellipse or arc.

Parameter Type Example Description
params_size size {"string": "100 x 100"} or {"string": "image"} Ellipse dimensions
params_colour color {"string": "#E74C3CFF"} Stroke/fill color
params_stroke_width number {"num": 2} Stroke width (0 for no stroke)
params_fill boolean {"num": 1} 1=filled, 0=stroke only
params_angle_start angle {"num": -180} Arc start angle
params_angle_end angle {"num": 180} Arc end angle

Full circle: Use angle_start: -180 and angle_end: 180

NodeType.rectangle

Draws a rectangle with optional rounded corners.

Parameter Type Example Description
params_size size {"string": "150 x 100"} Rectangle dimensions
params_colour color {"string": "#3498DBFF"} Stroke/fill color
params_stroke_width number {"num": 0} Stroke width
params_fill boolean {"num": 1} 1=filled, 0=stroke only
params_corner_radius number {"num": 10} Corner radius (0 for sharp)

Transform Nodes

NodeType.rotate

Rotates an image.

Parameter Type Example Description
params_rotation_angle angle {"num": 15} Rotation angle (-180 to 180)
params_keep_bounds boolean {"num": 1} 1=expand canvas to fit, 0=clip

NodeType.gaussianblur

Applies Gaussian blur.

Parameter Type Example Description
params_radius number {"num": 3} Blur radius (higher = more blur)

NodeType.edgedetect

Detects edges in an image.

Parameter Type Example Description
params_radius number {"num": 1} Detection radius

NodeType.invert

Inverts image colors. No parameters.

NodeType.adjusthsv

Adjusts hue, saturation, and value.

Parameter Type Example Description
params_hue number {"num": 30} Hue shift in degrees
params_saturation number {"num": 1.2} Saturation multiplier
params_value number {"num": 1.0} Value/brightness multiplier

NodeType.adjustbcg

Adjusts brightness, contrast, and gamma.

Parameter Type Example Description
params_brightness number {"num": 1.1} Brightness multiplier
params_contrast number {"num": 1.2} Contrast multiplier
params_gamma number {"num": 1.0} Gamma value

NodeType.resizepercent

Resizes by percentage.

Parameter Type Example Description
params_percent number {"num": 80} Scale percentage
params_maintain_aspect_ratio boolean {"num": 1} 1=maintain ratio

NodeType.resizeabsolute

Resizes to exact dimensions.

Parameter Type Example Description
params_size size {"string": "350 x 350"} Target dimensions
params_maintain_aspect_ratio boolean {"num": 0} 1=maintain ratio (may crop)

NodeType.smartcrop

Intelligently crops to dimensions.

Parameter Type Example Description
params_size size {"string": "300 x 300"} Target dimensions

Combination Nodes

NodeType.merge

Blends foreground over background.

Parameter Type Example Description
params text {"string": "Normal"} Blend mode (see Merge Modes)

Inputs: bg_input (background), fg_input (foreground)

NodeType.insertinto

Positions foreground on background at specific location.

Parameter Type Example Description
params_position position {"string": "50 x 100"} X x Y offset, or “center”

Inputs: bg_input (background), fg_input (foreground)

NodeType.composite

Composites multiple layers onto a base image with flexible positioning. Unlike merge which only handles two images, composite supports unlimited layers with individual positioning for each.

Parameter Type Example Description
layer_count number {"num": 5} Total number of layers (including base)
layer_N_position position {"string": "center"} Position for layer N (see Composite Positions)

Inputs: Dynamic based on layer_count:

  • layer_0 - Base/background layer (usually positioned at “0 x 0”)
  • layer_1 through layer_N - Overlay layers composited in order

Note: The layer_count value determines how many layer inputs are available. Layer 0 is typically the base canvas.

NodeType.mask

Applies a mask image to the source image using luminance-based masking. White areas in the mask show the source image, black areas become transparent, and gray values create partial transparency.

Parameter Type Example Description
params_offset position {"string": "0 x 0"} Position offset for placing the mask on the source
params_default_white boolean {"num": 0} 1=areas outside mask are visible, 0=transparent

Inputs:

  • source_input (required) - Image to be masked
  • mask_input (required) - Mask image (white=visible, black=transparent, gray=partial)

Output: output (masked image with transparency)

Examples:

  • Cut out a circular area using a white circle on black background as mask
  • Apply a gradient fade effect using a gradient (white to black) as the mask
  • Create a vignette effect by masking with a radial gradient (white center, black edges)

Utility Nodes

NodeType.attributes

Extracts image dimensions as a Size value for use in other nodes. Useful for dynamic sizing calculations.

Parameter Type Example Description
(none) - - No parameters required

Input: input (required) - Image to get attributes from

Output: output (size string, e.g., “800 x 600”)

Examples:

  • Get image size to calculate resize percentages
  • Extract dimensions for dynamic positioning
  • Feed image size to Size Maths node for calculations

NodeType.sizemaths

Performs mathematical operations on Size values (add, subtract, multiply, divide). Useful for calculating dynamic dimensions.

Parameter Type Example Description
params_type text {"string": "Multiply"} Operation: Multiply, Divide, Add, Subtract
params_value_x number {"num": 2} X value for calculation
params_value_y number {"num": 2} Y value for calculation

Input: input (required) - Size value or image (extracts dimensions from image)

Output: output (calculated size string)

Examples:

  • Double image dimensions by multiplying by 2
  • Calculate half-size for thumbnails (divide by 2)
  • Add padding to dimensions (add 20 to both axes)

Note: Results are capped between 0 and 10000 pixels per dimension.

NodeType.api

Exposes a parameter that can be provided at runtime via API calls. Allows dynamic pipeline configuration without modifying the pipeline structure.

Parameter Type Example Description
params_key text {"string": "title"} Parameter key name for API access
params_data_type text {"string": "text"} Data type: text, number, color, size, url, bool

Output: _connection (value of the specified data type)

Supported Data Types:

  • text - String values
  • number - Numeric values
  • color - 8-digit hex color (e.g., “#FF5733FF”)
  • size - Dimensions (e.g., “800x600”)
  • url - Valid HTTP/HTTPS URL
  • bool - Boolean (true/false)

Examples:

  • Create a dynamic text parameter for watermark customization
  • Expose a color parameter for runtime theme changes
  • Allow API callers to provide custom URLs or dimensions

NodeType.nestedpipeline

Executes another pipeline as a node, enabling modular and reusable image processing workflows. The nested pipeline’s API parameters become inputs to this node.

Parameter Type Example Description
node_id text {"string": "550e8400-e29b-41d4-a716-446655440000"} UUID of the pipeline to execute

Output: output (image from the nested pipeline’s output)

Examples:

  • Reuse common image processing sequences across multiple pipelines
  • Create modular, composable pipelines
  • Execute pre-built effects as subroutines

Note: Nested pipelines have a maximum depth limit to prevent infinite recursion. The cost of a nested pipeline includes the cost of all nodes within it.

Output Node

NodeType.output

Final output node. No parameters.

Input: input (single image input)

Common Node Patterns

Simple Canvas → Output

{
  "nodes": {
    "canvas": {"id": "canvas", "name": "BG", "node_type": "NodeType.solidcanvas", "position_x": 0, "position_y": 0},
    "out": {"id": "out", "name": "Out", "node_type": "NodeType.output", "position_x": 200, "position_y": 0}
  },
  "connectionMapFwd": {"canvas_output": ["out_input"]},
  "connectionMapRev": {"out_input": "canvas_output"}
}

Text Over Background (using Merge)

{
  "nodes": {
    "bg": {"id": "bg", "name": "Background", "node_type": "NodeType.solidcanvas", "position_x": 0, "position_y": 0},
    "text": {"id": "text", "name": "Text", "node_type": "NodeType.text", "position_x": 0, "position_y": 100},
    "merge": {"id": "merge", "name": "Merge", "node_type": "NodeType.merge", "position_x": 200, "position_y": 50},
    "out": {"id": "out", "name": "Output", "node_type": "NodeType.output", "position_x": 400, "position_y": 50}
  },
  "connectionMapFwd": {
    "bg_output": ["merge_bg_input"],
    "text_output": ["merge_fg_input"],
    "merge_output": ["out_input"]
  },
  "connectionMapRev": {
    "merge_bg_input": "bg_output",
    "merge_fg_input": "text_output",
    "out_input": "merge_output"
  }
}

Multi-Layer Composition (using Composite)

Use composite when you need to position multiple elements on a canvas. More efficient than chaining multiple merge nodes.

{
  "nodes": {
    "canvas": {"id": "canvas", "name": "Base", "node_type": "NodeType.solidcanvas", "position_x": 0, "position_y": 0},
    "badge1": {"id": "badge1", "name": "Top Left Badge", "node_type": "NodeType.ellipse", "position_x": 0, "position_y": 100},
    "badge2": {"id": "badge2", "name": "Top Right Badge", "node_type": "NodeType.ellipse", "position_x": 0, "position_y": 200},
    "title": {"id": "title", "name": "Title", "node_type": "NodeType.text", "position_x": 0, "position_y": 300},
    "composite": {"id": "composite", "name": "Compose", "node_type": "NodeType.composite", "position_x": 200, "position_y": 150},
    "out": {"id": "out", "name": "Output", "node_type": "NodeType.output", "position_x": 400, "position_y": 150}
  },
  "values": {
    "canvas_params_size": {"string": "800 x 600"},
    "canvas_params_colour": {"string": "#2C3E50FF"},
    "badge1_params_size": {"string": "60 x 60"},
    "badge1_params_colour": {"string": "#E74C3CFF"},
    "badge1_params_fill": {"num": 1},
    "badge1_params_stroke_width": {"num": 0},
    "badge1_params_angle_start": {"num": -180},
    "badge1_params_angle_end": {"num": 180},
    "badge2_params_size": {"string": "60 x 60"},
    "badge2_params_colour": {"string": "#3498DBFF"},
    "badge2_params_fill": {"num": 1},
    "badge2_params_stroke_width": {"num": 0},
    "badge2_params_angle_start": {"num": -180},
    "badge2_params_angle_end": {"num": 180},
    "title_params_text": {"string": "COMPOSITE"},
    "title_params_width": {"num": 600},
    "title_params_font": {"string": "Orbitron"},
    "title_params_colour": {"string": "#ECF0F1FF"},
    "composite_layer_0_position": {"string": "0 x 0"},
    "composite_layer_1_position": {"string": "top-left"},
    "composite_layer_2_position": {"string": "top-right"},
    "composite_layer_3_position": {"string": "center"},
    "composite_layer_count": {"num": 4}
  },
  "connectionMapFwd": {
    "canvas_output": ["composite_layer_0"],
    "badge1_output": ["composite_layer_1"],
    "badge2_output": ["composite_layer_2"],
    "title_output": ["composite_layer_3"],
    "composite_output": ["out_input"]
  },
  "connectionMapRev": {
    "composite_layer_0": "canvas_output",
    "composite_layer_1": "badge1_output",
    "composite_layer_2": "badge2_output",
    "composite_layer_3": "title_output",
    "out_input": "composite_output"
  }
}

Python Example

import requests
import base64

API_KEY = "your_api_key"
BASE_URL = "https://imagenodes.com/api/v1"

# Simple blue canvas
pipeline = {
    "id": "12345678-1234-1234-1234-123456789abc",
    "nodes": {
        "canvas": {
            "id": "canvas",
            "name": "Background",
            "node_type": "NodeType.solidcanvas",
            "position_x": 0,
            "position_y": 0
        },
        "out": {
            "id": "out",
            "name": "Output",
            "node_type": "NodeType.output",
            "position_x": 200,
            "position_y": 0
        }
    },
    "values": {
        "canvas_params_size": {"string": "1200 x 630"},
        "canvas_params_colour": {"string": "#3498dbFF"}
    },
    "connectionMapFwd": {
        "canvas_output": ["out_input"]
    },
    "connectionMapRev": {
        "out_input": "canvas_output"
    }
}

response = requests.post(
    f"{BASE_URL}/pipeline/evaluate",
    headers={"X-API-KEY": API_KEY},
    json={"pipeline": pipeline}
)

result = response.json()
if result["data"]["success"]:
    img_data = base64.b64decode(result["data"]["output"])
    with open("output.png", "wb") as f:
        f.write(img_data)
    print(f"Image saved! Cost: {result['data']['cost']} credits")
else:
    print(f"Error: {result['data']['error']}")

Error Codes

HTTP Code Meaning
200 Success (check data.success for execution result)
400 Invalid request body or pipeline structure
401 Invalid or missing API key
402 Insufficient credits
403 Paid subscription required
429 Rate limit exceeded
500 Server error

Complete Example: Social Media Banner

This complete example creates a gradient background with a title and subtitle - suitable for social media graphics.

{
  "pipeline": {
    "id": "11111111-2222-3333-4444-555555555555",
    "nodes": {
      "gradientBg": {
        "id": "gradientBg",
        "name": "Gradient Background",
        "node_type": "NodeType.gradientcanvas",
        "position_x": 0,
        "position_y": 0
      },
      "titleText": {
        "id": "titleText",
        "name": "Title",
        "node_type": "NodeType.text",
        "position_x": 0,
        "position_y": 150
      },
      "subtitle": {
        "id": "subtitle",
        "name": "Subtitle",
        "node_type": "NodeType.paragraph",
        "position_x": 0,
        "position_y": 300
      },
      "mergeTitle": {
        "id": "mergeTitle",
        "name": "Add Title",
        "node_type": "NodeType.merge",
        "position_x": 200,
        "position_y": 75
      },
      "mergeSubtitle": {
        "id": "mergeSubtitle",
        "name": "Add Subtitle",
        "node_type": "NodeType.merge",
        "position_x": 400,
        "position_y": 150
      },
      "out": {
        "id": "out",
        "name": "Output",
        "node_type": "NodeType.output",
        "position_x": 600,
        "position_y": 150
      }
    },
    "values": {
      "gradientBg_params_size": {"string": "1200 x 630"},
      "gradientBg_params_colour_start": {"string": "#667EBAFF"},
      "gradientBg_params_colour_end": {"string": "#0B8793FF"},
      "gradientBg_params_gradient_angle": {"num": 135},
      "titleText_params_text": {"string": "Welcome to ImageNodes"},
      "titleText_params_width": {"num": 1100},
      "titleText_params_font": {"string": "Orbitron"},
      "titleText_params_colour": {"string": "#FFFFFFFF"},
      "subtitle_params_text": {"string": "Create stunning graphics with AI-powered pipelines"},
      "subtitle_params_size": {"string": "800 x 100"},
      "subtitle_params_font": {"string": "OpenSans"},
      "subtitle_params_font_size": {"num": 24},
      "subtitle_params_line_height": {"num": 1.4},
      "subtitle_params_align": {"string": "center"},
      "subtitle_params_colour": {"string": "#FFFFFFCC"},
      "mergeTitle_params": {"string": "Normal"},
      "mergeSubtitle_params": {"string": "Normal"}
    },
    "connectionMapFwd": {
      "gradientBg_output": ["mergeTitle_bg_input"],
      "titleText_output": ["mergeTitle_fg_input"],
      "mergeTitle_output": ["mergeSubtitle_bg_input"],
      "subtitle_output": ["mergeSubtitle_fg_input"],
      "mergeSubtitle_output": ["out_input"]
    },
    "connectionMapRev": {
      "mergeTitle_bg_input": "gradientBg_output",
      "mergeTitle_fg_input": "titleText_output",
      "mergeSubtitle_bg_input": "mergeTitle_output",
      "mergeSubtitle_fg_input": "subtitle_output",
      "out_input": "mergeSubtitle_output"
    }
  }
}

This example demonstrates:

  • Using a gradient background with angled gradient
  • Layering text with the Merge node
  • Proper 8-digit hex colors with alpha channel
  • Numeric alignment for paragraph text
  • Correct connection patterns for multi-layer composition

Getting Started

  1. Create an account
  2. Subscribe to a paid plan
  3. Generate an API key from your dashboard
  4. Call /schema/nodes to discover available operations
  5. Build and execute pipelines!

For the full API documentation including stored pipeline management, see the API Documentation (requires login).