Image Generation Overview

JsonCut's image generation system allows you to create stunning images programmatically using simple JSON configurations. Whether you need social media graphics, marketing materials, or dynamic content, our flexible layer-based system has you covered.

Basic Structure

Every image generation job follows this basic structure:

{
  "type": "image",
  "config": {
    "width": 800,
    "height": 600,
    "backgroundColor": "#ffffff",
    "format": "png",
    "quality": 90,
    "layers": [
      // Your layers go here
    ]
  }
}

Core Properties

Property	Type	Required	Description
width	number	✅	Canvas width in pixels (max 4096px)
height	number	✅	Canvas height in pixels (max 4096px)
backgroundColor	string	❌	Background color (default: transparent)
format	string	❌	Output format: png, jpeg, webp (default: png)
quality	number	❌	Quality for JPEG/WebP (1-100, default: 90)
layers	array	✅	Array of layer objects (max 50 layers)

Layer System

Images are built using a layer-based system where each layer is rendered in order from bottom to top. JsonCut supports these layer types:

• Image - Display uploaded images with positioning and effects
• Text - Add text with custom fonts, colors, and styling
• Rectangle - Create solid or outlined rectangular shapes
• Circle - Add circular elements and shapes
• Gradient - Apply linear or radial color gradients

Common Layer Properties

All layers support these common properties:

{
  "type": "text",
  "x": 100,
  "y": 50,
  "width": 200,
  "height": 100,
  "opacity": 0.8,
  "rotation": 15,
  "blur": 2
}

Property	Type	Description
x, y	number	Position in pixels from top-left
width, height	number	Layer dimensions in pixels
opacity	number	Transparency (0-1, where 1 is opaque)
rotation	number	Rotation in degrees
blur	number	Blur radius in pixels

Working with Defaults

To avoid repetition, you can define default properties that apply to all layers or specific layer types:

{
  "type": "image",
  "config": {
    "width": 800,
    "height": 600,
    "defaults": {
      "layer": {
        "opacity": 0.9
      },
      "layerType": {
        "text": {
          "fontFamily": "Arial",
          "fontSize": 24,
          "color": "#333333"
        },
        "rectangle": {
          "fill": "#007acc",
          "stroke": "#004d7a",
          "strokeWidth": 2
        }
      }
    },
    "layers": [
      {
        "type": "text",
        "text": "Hello World",
        "x": 50,
        "y": 100
        // fontSize, color, fontFamily inherited from defaults
      },
      {
        "type": "rectangle",
        "x": 200,
        "y": 150,
        "width": 100,
        "height": 50
        // fill, stroke, strokeWidth inherited from defaults
      }
    ]
  }
}

Default Hierarchy

Defaults are applied in this order (later overrides earlier):

1. Global layer defaults (defaults.layer) - Applied to all layers
2. Layer type defaults (defaults.layerType.{type}) - Applied to specific layer types
3. Individual layer properties - Highest priority

Simple Example

Here's a complete example that creates a simple social media post:

{
  "type": "image",
  "config": {
    "width": 1200,
    "height": 630,
    "backgroundColor": "#3C27F5",
    "layers": [
      {
        "type": "gradient",
        "x": 15,
        "y": 15,
        "width": 1170,
        "height": 600,
        "gradient": {
          "type": "linear",
          "colors": ["#667eea", "#764ba2"],
          "direction": "diagonal"
        }
      },
      {
        "type": "text",
        "text": "Welcome to JsonCut",
        "x": 600,
        "y": 250,
        "fontSize": 72,
        "color": "#ffffff",
        "align": "center"
      },
      {
        "type": "text",
        "text": "Generate images with JSON",
        "x": 600,
        "y": 350,
        "fontSize": 32,
        "color": "#ffffff",
        "align": "center",
        "opacity": 0.9
      }
    ]
  }
}

Output Formats

JsonCut supports multiple output formats optimized for different use cases:

PNG (Default)

• Best for: Graphics with transparency, logos, screenshots
• Compression: Lossless
• Transparency: Supported
• File size: Larger but highest quality

JPEG

• Best for: Photos, complex images without transparency
• Compression: Lossy with quality control (1-100)
• Transparency: Not supported
• File size: Smaller with good quality

{
  "type": "image",
  "config": {
    "format": "jpeg",
    "quality": 80,
    "width": 1200,
    "height": 630,
    "backgroundColor": "#3C27F5",
    "layers": [...]
  }
}

WebP

• Best for: Modern web applications
• Compression: Lossy with quality control (1-100)
• Transparency: Supported
• File size: Smallest with excellent quality

{
  "type": "image",
  "config": {
    "format": "webp",
    "quality": 85,
    "width": 500,
    "height": 500,
    "layers": [...]
  }
}

Next Steps

Ready to dive deeper? Explore these topics:

• Layer Types - Complete guide to all available layer types
• Positioning System - Advanced positioning and alignment options
• Text Rendering - Typography, custom fonts, and text effects
• Visual Effects - Filters, transforms, and visual enhancements
• Examples - Real-world examples and use cases

Token Usage

For more details, see our Rate Limits & Tokens guide.