Image Templates

Image Templates let you compose complex images from multiple layers including images, text, shapes, SVGs, and AI-generated content. Templates are defined once and can be rendered on demand with dynamic variable substitution.

How Templates Work

A template defines a canvas with one or more layers. Each layer has a type (image, text, shape, SVG, or AI image), positioning, blend mode, effects, and opacity. When you render a template, PixelFiddler composites all layers together and returns the resulting image.

Templates are managed per space and referenced by name.

Limits

Max layers per template: 20
Max image layers per template: 3
Max SVG layers per template: 10
Max templates per space: 100

Canvas

The canvas defines the base for your composition.

Property	Description
`dimensions`	Width and height of the canvas in pixels (optional)
`image`	A base image layer to use as the canvas background (optional)
`backgroundColor`	Background color in hex format (optional)

If no dimensions are provided, the canvas size is determined by the base image or the first layer’s dimensions.

Layer Types

Image Layer

Displays an image from a connected media source. Supports all standard transformations and effects.

Property	Description
`defaultSourcePath`	Reference to a media source and file path
`effects`	List of effects to apply (blur, brightness, contrast, etc.)
`asyncTransformations`	AI transformations (background removal, AI edit)

Text Layer

Renders styled text on the canvas. Supports all text transformation parameters including font, color, size, shadow, and positioning.

Property	Description
`text`	The text content to display
`color`	Text color in hex format
`font`	Font family name
`fontSize`	Font size in pixels
`fontWeight`	Font weight (e.g. 400, 700)
`opacity`	Text opacity (0-100)
`background`	Background color behind text
`shadow`	Shadow settings (color, blur, x, y, opacity)

Shape Layer

Renders geometric shapes on the canvas.

SVG Layer

Renders raw SVG content directly on the canvas.

Property	Description
`content`	Raw SVG string

AI Image Layer

Generates an image using AI models from a text prompt.

Property	Description
`defaultPrompt`	Text prompt for AI image generation (optional)
`dimensions`	Required width and height for the generated image
`model`	AI model tier: `BASIC` or `QUALITY`

Layer Properties

Every layer (regardless of type) supports these common properties:

Property	Description
`position`	X and Y coordinates for layer placement
`dimensions`	Optional width and height of the layer
`angle`	Rotation angle in degrees
`opacity`	Layer transparency (0-100)
`fitMode`	How the layer fits within its bounds: `CROP` or `RESIZE`
`blendMode`	Compositing blend mode (see below)
`effects`	Visual effects applied to the layer

Blend Modes

The following blend modes are available for layer compositing:

OVER, MULTIPLY, SCREEN, OVERLAY, DARKEN, LIGHTEN, COLOR_DODGE, COLOR_BURN, HARD_LIGHT, SOFT_LIGHT, DIFFERENCE, EXCLUSION, and more.

Template Variables

Templates support dynamic variables that can be substituted at render time:

String variables - Replace text content dynamically
Media source path variables - Swap images dynamically

Variables are defined in the template and provided as parameters when generating the image.

GIF Templates

Create animated GIFs by defining multiple frames, each as its own image template.

Property	Description
`delay`	Frame delay in milliseconds
`loops`	Number of animation loops (-1 for infinite)
`frames`	List of image templates, one per frame

API Reference

List Templates

GET /accounts/self/spaces/{spaceId}/image-templates

Returns all templates in the specified space.

Create or Update Template

PUT /accounts/self/spaces/{spaceId}/image-templates/{templateName}

Create a new template or update an existing one. Template names must be unique within a space.

Example request body:

{
  "canvas": {
    "backgroundColor": "ffffff",
    "dimensions": {
      "width": 800,
      "height": 600
    }
  },
  "layers": [
    {
      "type": "IMAGE",
      "name": "background",
      "descriptor": {
        "position": { "x": 0, "y": 0 },
        "opacity": 100,
        "blendMode": "OVER"
      },
      "defaultSourcePath": {
        "sourceAlias": "my-source",
        "filePath": "backgrounds/hero.jpg"
      }
    },
    {
      "type": "TEXT",
      "name": "title",
      "descriptor": {
        "position": { "x": 50, "y": 50 },
        "opacity": 100
      },
      "text": "Hello World",
      "color": "000000",
      "fontSize": 48,
      "fontWeight": 700
    }
  ]
}

Delete Template

DELETE /accounts/self/spaces/{spaceId}/image-templates/{templateName}

Generate Image from Template

POST /sources/{sourceId}/images

Renders a template and returns the generated image. Pass template variables in the request body to dynamically substitute content.

Generate GIF from Template

POST /sources/{sourceId}/gifs

Renders a multi-frame GIF template and returns the generated animation.