Screenshot composition

Combine multiple screenshots into a single image with automatic layout, labels, and styling. Perfect for comparison images, galleries, and social media content.

Endpoint

POST /v1/screenshots/compose

Modes

The compose API supports two modes:

Captures mode

Capture multiple different URLs:

{
  "captures": [
    { "url": "https://site1.com", "label": "Site 1" },
    { "url": "https://site2.com", "label": "Site 2" },
    { "url": "https://site3.com", "label": "Site 3" }
  ],
  "output": {
    "layout": "grid"
  }
}

Variants mode

Capture one URL with different configurations:

{
  "url": "https://example.com",
  "variants": [
    { "device": "desktop_hd", "label": "Desktop" },
    { "device": "iphone_15", "label": "iPhone" },
    { "device": "ipad_pro_11", "label": "iPad" }
  ],
  "output": {
    "layout": "horizontal"
  }
}

Layout types

Layout	Description
`auto`	Automatically selects the best layout based on image count and dimensions
`grid`	Equal-sized cells in rows and columns
`horizontal`	Single row, all images side by side
`vertical`	Single column, all images stacked
`masonry`	Pinterest-style staggered layout
`mondrian`	Abstract art-inspired geometric blocks
`partitioning`	Balanced rows like Google Photos/Telegram

Request body

Captures mode

{
  "captures": [
    {
      "url": "https://example.com",
      "id": "capture-1",
      "label": "Example Site",
      "viewport": { "width": 1280, "height": 720 },
      "device": null,
      "fullPage": false,
      "darkMode": false,
      "delay": 0
    }
  ],
  "defaults": {
    "viewport": { "width": 1920, "height": 1080 },
    "format": "png",
    "quality": 80,
    "fullPage": false,
    "delay": 0,
    "waitFor": null,
    "waitUntil": "load",
    "timeout": 30000,
    "darkMode": false,
    "customCss": null,
    "hideSelectors": [],
    "blockAds": false,
    "blockCookieBanners": false,
    "blockLevel": "none"
  },
  "output": { ... },
  "async": false,
  "webhookUrl": null,
  "webhookSecret": null
}

Output options

{
  "output": {
    "layout": "grid",
    "format": "png",
    "quality": 90,
    "columns": 2,
    "spacing": 10,
    "padding": 20,
    "background": "#ffffff",
    "alignment": "center",
    "maxWidth": 2000,
    "maxHeight": 2000,
    "thumbnailWidth": null,
    "labels": {
      "show": true,
      "position": "bottom",
      "fontSize": 14,
      "fontColor": "#333333",
      "background": "#ffffff",
      "padding": 8
    },
    "border": {
      "width": 1,
      "color": "#cccccc",
      "radius": 8
    },
    "shadow": {
      "enabled": true,
      "blur": 10,
      "offsetX": 0,
      "offsetY": 4,
      "color": "rgba(0,0,0,0.2)"
    }
  }
}

Output parameters

Parameter	Type	Default	Description
`layout`	string	`"auto"`	Layout algorithm
`format`	string	`"png"`	Output format: `png`, `jpeg`, `webp`
`quality`	integer	`90`	Image quality (1-100)
`columns`	integer	auto	Fixed number of columns (grid layout)
`spacing`	integer	`10`	Space between images (0-100px)
`padding`	integer	`0`	Padding around edges (0-100px)
`background`	string	`"#ffffff"`	Background color or `"transparent"`
`alignment`	string	`"center"`	Vertical alignment: `top`, `center`, `bottom`
`maxWidth`	integer	-	Maximum output width (100-10000)
`maxHeight`	integer	-	Maximum output height (100-10000)
`thumbnailWidth`	integer	-	Resize captures to this width (50-2000)

Label options

Parameter	Type	Default	Description
`show`	boolean	`true`	Show labels
`position`	string	`"bottom"`	Position: `top` or `bottom`
`fontSize`	integer	`14`	Font size (8-48)
`fontColor`	string	`"#333333"`	Text color
`background`	string	`"#ffffff"`	Label background
`padding`	integer	`8`	Label padding (0-20)

Border options

Parameter	Type	Default	Description
`width`	integer	`1`	Border width (0-10)
`color`	string	`"#cccccc"`	Border color
`radius`	integer	`0`	Corner radius (0-20)

Shadow options

Parameter	Type	Default	Description
`enabled`	boolean	`true`	Show shadow
`blur`	integer	`10`	Shadow blur (0-50)
`offsetX`	integer	`0`	Horizontal offset (-20 to 20)
`offsetY`	integer	`4`	Vertical offset (-20 to 20)
`color`	string	`"rgba(0,0,0,0.2)"`	Shadow color

Examples

Side-by-side comparison

curl -X POST 'https://api.allscreenshots.com/v1/screenshots/compose' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "captures": [
      { "url": "https://old-design.example.com", "label": "Before" },
      { "url": "https://new-design.example.com", "label": "After" }
    ],
    "output": {
      "layout": "horizontal",
      "spacing": 20,
      "padding": 20,
      "background": "#f5f5f5"
    }
  }' --output comparison.png

Responsive showcase

curl -X POST 'https://api.allscreenshots.com/v1/screenshots/compose' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "variants": [
      { "device": "desktop_hd", "label": "Desktop" },
      { "device": "laptop", "label": "Laptop" },
      { "device": "ipad_pro_11", "label": "Tablet" },
      { "device": "iphone_15", "label": "Mobile" }
    ],
    "output": {
      "layout": "grid",
      "columns": 2,
      "spacing": 15,
      "border": { "width": 1, "color": "#e0e0e0", "radius": 8 },
      "shadow": { "enabled": true }
    }
  }' --output responsive.png

Photo gallery

curl -X POST 'https://api.allscreenshots.com/v1/screenshots/compose' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "captures": [
      { "url": "https://unsplash.com/photos/abc" },
      { "url": "https://unsplash.com/photos/def" },
      { "url": "https://unsplash.com/photos/ghi" },
      { "url": "https://unsplash.com/photos/jkl" },
      { "url": "https://unsplash.com/photos/mno" }
    ],
    "output": {
      "layout": "partitioning",
      "spacing": 4,
      "maxWidth": 1200
    }
  }' --output gallery.png

Dark vs light mode

curl -X POST 'https://api.allscreenshots.com/v1/screenshots/compose' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "variants": [
      { "darkMode": false, "label": "Light Mode" },
      { "darkMode": true, "label": "Dark Mode" }
    ],
    "output": {
      "layout": "horizontal",
      "background": "#1a1a1a",
      "labels": {
        "fontColor": "#ffffff",
        "background": "transparent"
      }
    }
  }' --output themes.png

Compositions count as one screenshot per captured URL. A composition of 4 URLs uses 4 screenshots from your quota.

Async composition

For large compositions, use async mode:

{
  "captures": [ ... ],
  "async": true,
  "webhookUrl": "https://your-server.com/webhooks/compose"
}

Returns a job ID that you can poll or receive via webhook when complete.

Compose

Screenshot composition

Endpoint

Modes

Captures mode

Variants mode

Layout types

Request body

Captures mode

Output options

Output parameters

Label options

Border options

Shadow options

Examples

Side-by-side comparison

Responsive showcase

Photo gallery

Dark vs light mode

Async composition

On this page