Image Generation

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

Key Features

• 8 Layer Types — Solid color backgrounds, rectangles (with optional angled edges), gradients (linear and radial), text (with markdown bold/italic), static images (with optional background removal), full-canvas image overlays, QR codes, and barcodes.
• 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.
• 98 Bundled 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 6 formats: Code 128, EAN-13, EAN-8, Code 39, ITF, and Codabar.
• Background Removal — Automatically remove backgrounds from static 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": 800, "height": 600 },
    "layers": [
      { "index": 0, "type": "solid-color-background", "hex_color": "#FFFFFF" },
      {
        "index": 1,
        "type": "text",
        "text": "Hello World",
        "font_name": "Roboto",
        "font_size_in_px": 48,
        "text_color": "#000000",
        "position": { "x": 50.0, "y": 50.0 },
        "dimensions": { "width": 700, "height": 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-background", 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",
});
// result.data.buffer is base64-encoded, result.data.mime_type is "image/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-background", "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",
)
# result["data"]["buffer"] is base64-encoded, result["data"]["mime_type"] is "image/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}),
    },
})
// result.Data.Buffer is base64-encoded, result.Data.MimeType is "image/png"

Top-Level Fields

Async Mode

Add a webhook_url parameter to process the request in the background. The API returns 201 Accepted immediately and delivers the result to your webhook URL when processing completes. See Webhooks for payload format and retry behavior.

Font Definition

98 font families 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
• 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.

Shared Layer Fields

All layer types share these base fields:

Layers that support positioning also include:

Layer Types

solid-color-background

A full-canvas solid color fill. Typically used as the bottom-most layer.

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

rectangle

A positioned rectangle with an optional solid fill and angled edges.

Angled Edges

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

{
  "index": 1,
  "type": "rectangle",
  "hex_color": "#3366FF",
  "position": { "x": 50.0, "y": 100.0 },
  "dimensions": { "width": 300, "height": 200 },
  "angled_edges": [
    { "edge": "right", "angle_in_degrees": 15.0 }
  ]
}

gradient

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

Color Stop

{
  "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": 0.0, "y": 0.0 },
  "dimensions": { "width": 800, "height": 600 }
}

text

Render text with custom fonts, alignment, and optional markdown formatting. Supports **bold** and *italic* syntax. When should_auto_scale is true, the font size is automatically scaled down from font_size_in_px until the text fits within the layer dimensions.

{
  "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": 100.0, "y": 200.0 },
  "dimensions": { "width": 600, "height": 150 }
}

static-image

A positioned image. Provide the image as base64-encoded data.

When should_use_smart_cropping is true, the image is cropped around detected faces, people, or objects using AI detection. When false, a standard cover-fit resize is used.

When should_remove_background is true, the image background is automatically removed using AI-powered segmentation before compositing. This is useful for placing product photos or portraits onto custom backgrounds.

{
  "index": 1,
  "type": "static-image",
  "buffer": "<base64-encoded-image>",
  "position": { "x": 50.0, "y": 50.0 },
  "dimensions": { "width": 200, "height": 200 },
  "should_use_smart_cropping": true,
  "should_remove_background": false
}

image-overlay

A full-canvas image overlay. The image is resized to fill the entire canvas.

{
  "index": 3,
  "type": "image-overlay",
  "buffer": "<base64-encoded-image>",
  "opacity": 50
}

qr-code

Generate a QR code with custom colors.

{
  "index": 2,
  "type": "qr-code",
  "value": "https://example.com",
  "position": { "x": 600.0, "y": 400.0 },
  "dimensions": { "width": 150, "height": 150 },
  "foreground_hex_color": "#000000",
  "background_hex_color": "#FFFFFF"
}

barcode

Generate a barcode in one of 6 supported formats.

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": 100.0, "y": 450.0 },
  "dimensions": { "width": 300, "height": 80 },
  "foreground_hex_color": "#000000",
  "background_hex_color": "#FFFFFF"
}

Recipes

For complete, runnable examples see the Recipes page.

• Generate Social Cards – Create Open Graph and Twitter card images dynamically from templates with custom text and branding.
• Create Certificate Images – Design award and completion certificates with dynamic recipient names and dates.
• Build Dynamic Email Banners – Compose personalized email header images with text overlays and branding.
• Create Listing Images – Generate product listing images with prices, badges, and backgrounds.
• Produce Report Charts – Build chart and infographic images from data for embedding in reports and dashboards.

Error Responses