Image Generation API

Generate composited images from layers — solid colors, gradients, text, images, QR codes, barcodes, and layouts.

Cost: 2 credits per request

Prerequisites

You need an Iteration Layer API key. Get one at platform.iterationlayer.com — free trial credits included, no credit card required.

For full integration guidance (SDKs, auth, MCP, error handling), see the Iteration Layer Integration Guide.

API Reference

Generate composited images from layer definitions with a single API call. Define a canvas, add layers — solid colors, gradients, text, images, QR codes, barcodes, layouts — and receive the rendered image as base64-encoded JSON in the response.

Key Features

• Layer Types — Solid colors (with optional angled edges and border radius), gradients (linear and radial, with border radius), text (with markdown bold/italic), images (with optional background removal and border radius), QR codes, barcodes, and layouts (horizontal/vertical flow with gap, alignment, padding, and nested children).
• Layer Compositing — Layers are rendered in index order and composited onto a transparent canvas with per-layer opacity and rotation.
• Text Rendering — Render text with custom fonts, alignment, and markdown formatting (

  **bold**

  and

  *italic*

  ). Supports line wrapping, vertical alignment, and automatic font size scaling.
• Bundled Google Fonts — The top Google Fonts are bundled and available by default, including Inter, Roboto, OpenSans, Montserrat, Poppins, Lato, and many more. No font upload required for most text rendering needs.
• Custom Fonts — Upload additional fonts as base64 (TTF, OTF, WOFF, WOFF2) for text rendering.
• QR Codes — Generate QR codes with custom foreground and background colors.
• Barcodes — Generate barcodes in multiple formats: Code 128, EAN-13, EAN-8, Code 39, ITF, and Codabar.
• Background Removal — Automatically remove backgrounds from images using AI-powered detection.
• Output Formats — PNG, JPEG, WebP, TIFF, GIF, or AVIF.

Overview

The Image Generation API composites multiple layers onto a canvas to produce a single output image. You define the canvas dimensions, optionally provide custom fonts, and specify an ordered list of layers. Each layer is rendered and composited by index order.

Endpoint:

POST /image-generation/v1/generate

Output formats: PNG (default), JPEG, WebP, TIFF, GIF, AVIF

Request Format

curl -X POST https://api.iterationlayer.com/image-generation/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": {
      "width_in_px": 800,
      "height_in_px": 600
    },
    "layers": [
      {
        "index": 0,
        "type": "solid-color",
        "hex_color": "#FFFFFF"
      },
      {
        "index": 1,
        "type": "text",
        "text": "Hello World",
        "font_name": "Roboto",
        "font_size_in_px": 48,
        "text_color": "#000000",
        "position": {
          "x_in_px": 50.0,
          "y_in_px": 50.0
        },
        "dimensions": {
          "width_in_px": 700,
          "height_in_px": 100
        }
      }
    ],
    "output_format": "png"
  }'

import { IterationLayer } from "iterationlayer";
const client = new IterationLayer({
  apiKey: "YOUR_API_KEY",
});

const result = await client.generateImage({
  dimensions: {
    width_in_px: 800,
    height_in_px: 600,
  },
  layers: [
    {
      index: 0,
      type: "solid-color",
      hex_color: "#FFFFFF",
    },
    {
      index: 1,
      type: "text",
      text: "Hello World",
      font_name: "Roboto",
      font_size_in_px: 48,
      text_color: "#000000",
      position: {
        x_in_px: 50,
        y_in_px: 50,
      },
      dimensions: {
        width_in_px: 700,
        height_in_px: 100,
      },
    },
  ],
  output_format: "png",
});

from iterationlayer import IterationLayer
client = IterationLayer(api_key="YOUR_API_KEY")

result = client.generate_image(
    dimensions={
        "width_in_px": 800,
        "height_in_px": 600,
    },
    layers=[
        {
            "index": 0,
            "type": "solid-color",
            "hex_color": "#FFFFFF",
        },
        {
            "index": 1,
            "type": "text",
            "text": "Hello World",
            "font_name": "Roboto",
            "font_size_in_px": 48,
            "text_color": "#000000",
            "position": {
                "x_in_px": 50,
                "y_in_px": 50,
            },
            "dimensions": {
                "width_in_px": 700,
                "height_in_px": 100,
            },
        },
    ],
    output_format="png",
)

import il "github.com/iterationlayer/sdk-go"
client := il.NewClient("YOUR_API_KEY")

result, err := client.GenerateImage(il.GenerateImageRequest{
    Dimensions: il.Dimensions{
        WidthInPx:  800,
        HeightInPx: 600,
    },
    OutputFormat: "png",
    Layers: []il.Layer{
        il.NewSolidColorBackgroundLayer(0, "#FFFFFF"),
        il.NewTextLayer(1, "Hello World", "Roboto", 48, "#000000",
            il.Position{
                XInPx: 50,
                YInPx: 50,
            },
            il.Dimensions{
                WidthInPx:  700,
                HeightInPx: 100,
            }),
    },
})

{
  "success": true,
  "data": {
    "buffer": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mime_type": "image/png"
  }
}

Top-Level Fields

dimensions

width

height

layers

output_format

png

jpeg

webp

tiff

gif

avif

fonts

webhook_url

Async Mode

Add a

webhook_url

201 Accepted

Font Definition

The top Google Fonts are bundled and available by default. Text layers can reference any bundled font by name without providing font definitions. If a text layer references a font name that isn't found, it falls back to Inter Regular.

Bundled fonts:

• AlfaSlabOne
• AnekTelugu
• Anton
• Archivo
• ArchivoBlack
• Arimo
• Assistant
• Barlow
• BarlowCondensed
• BebasNeue
• Bitter
• BricolageGrotesque
• Bungee
• Cabin
• Cairo
• Caveat
• ChangaOne
• CommitMono
• CormorantGaramond
• CrimsonText
• DancingScript
• DMSans
• Dosis
• EBGaramond
• Exo2
• Figtree
• FiraSans
• FjallaOne
• GravitasOne
• Heebo
• Hind
• HindSiliguri
• IBMPlexSans
• Inconsolata
• Inter
• InterTight
• JosefinSans
• Jost
• Kanit
• Karla
• Lato
• Lexend
• LibreBaskerville
• LibreFranklin
• Lobster
• Lora
• Manrope
• Merriweather
• Montserrat
• MPLUSRounded1c
• Mukta
• Mulish
• NanumGothic
• NotoSans
• NotoSansArabic
• NotoSansJP
• NotoSansKR
• NotoSansSC
• NotoSansTC
• NotoSansTelugu
• NotoSerif
• NotoSerifJP
• Nunito
• NunitoSans
• OpenSans
• Oswald
• Outfit
• Overpass
• Oxygen
• Pacifico
• PlayfairDisplay
• PlusJakartaSans
• Poppins
• Prompt
• PTSans
• PTSerif
• PublicSans
• Quicksand
• Raleway
• Ramabhadra
• RedHatDisplay
• Roboto
• RobotoCondensed
• RobotoFlex
• RobotoMono
• RobotoSlab
• Rubik
• Saira
• SchibstedGrotesk
• ShareTech
• Slabo27px
• SmoochSans
• Sora
• SourceCodePro
• SourceSans3
• SpaceGrotesk
• TitilliumWeb
• Ubuntu
• WorkSans

To use additional fonts beyond the bundled set, provide them as base64-encoded font files. Fonts are matched by name, weight, and style.

name

weight

thin

extralight

light

regular

medium

semibold

bold

extrabold

black

style

normal

italic

buffer

Shared Layer Fields

All layer types share these base fields:

index

type

opacity

Layers that support positioning also include:

position

x

y

dimensions

width

height

rotation_in_degrees

Layer Types

solid-color

A solid color fill. When

position

dimensions

hex_color

#FF5500

position

dimensions

rotation_in_degrees

border_radius

border_top_left_radius

border_top_right_radius

border_bottom_left_radius

border_bottom_right_radius

angled_edges

Set either

border_radius

{
  "index": 0,
  "type": "solid-color",
  "hex_color": "#FFFFFF"
}

Positioned with rounded corners:

{
  "index": 1,
  "type": "solid-color",
  "hex_color": "#3366FF",
  "position": {
    "x_in_px": 50.0,
    "y_in_px": 100.0
  },
  "dimensions": {
    "width_in_px": 300,
    "height_in_px": 200
  },
  "border_radius": 24
}

Angled Edges

Each angled edge definition cuts one side of the layer at an angle:

edge

left

right

top

bottom

angle_in_degrees

{
  "index": 1,
  "type": "solid-color",
  "hex_color": "#3366FF",
  "position": {
    "x_in_px": 50.0,
    "y_in_px": 100.0
  },
  "dimensions": {
    "width_in_px": 300,
    "height_in_px": 200
  },
  "angled_edges": [
    {
      "edge": "right",
      "angle_in_degrees": 15.0
    }
  ]
}

gradient

A positioned gradient fill. Supports linear and radial gradients with configurable color stops and rounded corners.

gradient_type

linear

radial

colors

position

dimensions

angle_in_degrees

rotation_in_degrees

border_radius

border_top_left_radius

border_top_right_radius

border_bottom_left_radius

border_bottom_right_radius

Color Stop

hex_color

#FF0000

position

{
  "index": 1,
  "type": "gradient",
  "gradient_type": "linear",
  "angle_in_degrees": 90.0,
  "colors": [
    {
      "hex_color": "#FF0000",
      "position": 0.0
    },
    {
      "hex_color": "#0000FF",
      "position": 100.0
    }
  ],
  "position": {
    "x_in_px": 0.0,
    "y_in_px": 0.0
  },
  "dimensions": {
    "width_in_px": 800,
    "height_in_px": 600
  }
}

text

Render text with custom fonts, alignment, and optional markdown formatting. Supports

**bold**

*italic*

should_auto_scale

true

font_size_in_px

text

**bold**

*italic*

font_name

font_size_in_px

text_color

#000000

position

dimensions

font_weight

thin

extralight

light

regular

medium

semibold

bold

extrabold

black

font_style

normal

italic

text_align

left

center

right

vertical_align

top

center

bottom

is_splitting_lines

true

paragraph_spacing_in_px

should_auto_scale

false

rotation_in_degrees

{
  "index": 2,
  "type": "text",
  "text": "**Important:** This is *formatted* text.",
  "font_name": "Inter",
  "font_size_in_px": 24,
  "text_color": "#333333",
  "text_align": "center",
  "vertical_align": "center",
  "position": {
    "x_in_px": 100.0,
    "y_in_px": 200.0
  },
  "dimensions": {
    "width_in_px": 600,
    "height_in_px": 150
  }
}

image

An image layer. Provide the image as base64-encoded data or a URL. When

position

dimensions

file

position

dimensions

rotation_in_degrees

should_use_smart_cropping

false

should_remove_background

false

border_radius

border_top_left_radius

border_top_right_radius

border_bottom_left_radius

border_bottom_right_radius

The

file

type

"base64"

"url"

name

"photo.png"

base64

type

"base64"

url

type

"url"

When

should_use_smart_cropping

true

false

When

should_remove_background

true

Positioned with rounded corners:

{
  "index": 1,
  "type": "image",
  "file": {
    "type": "base64",
    "name": "photo.png",
    "base64": "<base64-data>"
  },
  "position": {
    "x_in_px": 50.0,
    "y_in_px": 50.0
  },
  "dimensions": {
    "width_in_px": 200,
    "height_in_px": 200
  },
  "border_radius": 16,
  "should_use_smart_cropping": true
}

Full-canvas overlay:

{
  "index": 3,
  "type": "image",
  "file": {
    "type": "base64",
    "name": "overlay.png",
    "base64": "<base64-data>"
  },
  "opacity": 50
}

qr-code

Generate a QR code with custom colors.

value

position

dimensions

foreground_hex_color

background_hex_color

rotation_in_degrees

{
  "index": 2,
  "type": "qr-code",
  "value": "https://example.com",
  "position": {
    "x_in_px": 600.0,
    "y_in_px": 400.0
  },
  "dimensions": {
    "width_in_px": 150,
    "height_in_px": 150
  },
  "foreground_hex_color": "#000000",
  "background_hex_color": "#FFFFFF"
}

barcode

Generate a barcode in one of the supported formats.

value

format

code128

ean13

ean8

code39

itf

codabar

position

dimensions

foreground_hex_color

background_hex_color

rotation_in_degrees

Format notes:

• ean13

  — Requires exactly 12 or 13 digits

• ean8

  — Requires exactly 7 or 8 digits

• itf

  — Requires an even number of digits

• codabar

  — Must start and end with A, B, C, or D

• code128

  — Supports alphanumeric characters

• code39

  — Supports uppercase letters, digits, and special characters

{
  "index": 3,
  "type": "barcode",
  "value": "ABC123456",
  "format": "code128",
  "position": {
    "x_in_px": 100.0,
    "y_in_px": 450.0
  },
  "dimensions": {
    "width_in_px": 300,
    "height_in_px": 80
  },
  "foreground_hex_color": "#000000",
  "background_hex_color": "#FFFFFF"
}

layout

A flow layout that arranges child layers horizontally or vertically. Supports gap spacing, cross-axis alignment, background color with padding and border radius, and optional fixed dimensions. Layout layers can be nested — child layers can include other layouts.

direction

"horizontal"

"vertical"

gap

horizontal_alignment

"start"

"center"

"end"

vertical_alignment

"start"

"center"

"end"

layers

position

dimensions

background_color

#336699

background_layers

background_color

padding

padding_top

padding_right

padding_bottom

padding_left

border_radius

border_top_left_radius

border_top_right_radius

border_bottom_left_radius

border_bottom_right_radius

Set either

padding

border_radius

When

dimensions

"auto"

Horizontal pill with icon and text:

{
  "index": 1,
  "type": "layout",
  "direction": "horizontal",
  "gap": 8,
  "vertical_alignment": "center",
  "background_color": "#0284c7",
  "padding": 12,
  "border_radius": 20,
  "position": {
    "x_in_px": 20.0,
    "y_in_px": 50.0
  },
  "layers": [
    {
      "type": "image",
      "file": {
        "type": "base64",
        "name": "icon.svg",
        "base64": "<base64-svg>"
      },
      "dimensions": {
        "width_in_px": 20,
        "height_in_px": 20
      }
    },
    {
      "type": "text",
      "text": "Click here",
      "font_name": "Inter",
      "font_size_in_px": 16,
      "text_color": "#FFFFFF",
      "dimensions": {
        "width_in_px": "auto",
        "height_in_px": 24
      }
    }
  ]
}

Vertical card with fixed dimensions:

{
  "index": 2,
  "type": "layout",
  "direction": "vertical",
  "gap": 12,
  "background_color": "#FFFFFF",
  "padding": 24,
  "border_radius": 16,
  "dimensions": {
    "width_in_px": 300,
    "height_in_px": 200
  },
  "position": {
    "x_in_px": 50.0,
    "y_in_px": 100.0
  },
  "layers": [
    {
      "type": "text",
      "text": "Card Title",
      "font_name": "Inter",
      "font_size_in_px": 24,
      "font_weight": "bold",
      "text_color": "#1e293b",
      "dimensions": {
        "width_in_px": 252,
        "height_in_px": 32
      }
    },
    {
      "type": "text",
      "text": "Card description text goes here.",
      "font_name": "Inter",
      "font_size_in_px": 14,
      "text_color": "#64748b",
      "dimensions": {
        "width_in_px": 252,
        "height_in_px": 60
      }
    }
  ]
}

Recipes

For complete, runnable examples see the Recipes page.

• Generate Social Card -- Create an Open Graph social sharing card with dynamic title, description, and branding.
• Generate Certificate Image -- Generate a certificate image with recipient name, course title, and completion date for digital sharing.
• Generate YouTube Thumbnail -- Generate a YouTube thumbnail with bold title text, gradient background, and a static image cutout.
• Generate Product Listing Image -- Generate a product listing image with photo, price badge, and promotional text overlay.
• Generate Event Ticket -- Generate a scannable event ticket image with QR code, event details, and branding.
• Generate Product Slide -- Generate a branded product slide with headline, feature pills, and CTA using layout layers.

Error Responses

Links

• Integration guide
• Full documentation
• OpenAPI spec
• Browse recipes