Viewport and devices

Control how pages are rendered by setting custom viewport dimensions or emulating real devices. This is essential for capturing responsive designs and mobile-specific layouts.

Custom viewport

Set exact viewport dimensions:

{
  "url": "https://example.com",
  "viewport": {
    "width": 1440,
    "height": 900,
    "deviceScaleFactor": 2
  }
}

Viewport parameters

Parameter	Type	Range	Default	Description
`width`	integer	100-4096	1920	Viewport width in CSS pixels
`height`	integer	100-4096	1080	Viewport height in CSS pixels
`deviceScaleFactor`	integer	1-3	1	Device pixel ratio (DPR)

Device scale factor

The deviceScaleFactor controls the pixel density:

1 - Standard display (96 DPI)
2 - Retina/HiDPI display (192 DPI)
3 - Ultra-high DPI (288 DPI)

Higher values produce sharper images but larger file sizes.

Device presets

Use device presets instead of manual viewport configuration:

{
  "url": "https://example.com",
  "device": "iphone_15"
}

Device presets automatically configure:

Viewport dimensions
Device scale factor
Mobile/touch behavior
User agent (where applicable)

Desktop devices

Preset	Dimensions	DPR	Description
`desktop_hd`	1920×1080	1	Standard HD desktop
`desktop_large`	2560×1440	1	Large/QHD desktop
`desktop_retina`	1920×1080	2	Retina desktop
`laptop`	1440×900	1	Standard laptop
`laptop_retina`	1440×900	2	MacBook Pro style

iPhone devices

Preset	Dimensions	DPR	Description
`iphone_se`	375×667	2	iPhone SE
`iphone_xr`	414×896	2	iPhone XR
`iphone_12`	390×844	3	iPhone 12
`iphone_12_pro_max`	428×926	3	iPhone 12 Pro Max
`iphone_14`	390×844	3	iPhone 14
`iphone_14_pro_max`	430×932	3	iPhone 14 Pro Max
`iphone_15`	393×852	3	iPhone 15
`iphone_15_pro_max`	430×932	3	iPhone 15 Pro Max

iPad devices

Preset	Dimensions	DPR	Description
`ipad`	768×1024	2	Standard iPad
`ipad_mini`	768×1024	2	iPad Mini
`ipad_pro_11`	834×1194	2	iPad Pro 11"
`ipad_pro_12_9`	1024×1366	2	iPad Pro 12.9"

Android devices

Preset	Dimensions	DPR	Description
`pixel_5`	393×851	2.75	Google Pixel 5
`pixel_7`	412×915	2.625	Google Pixel 7
`pixel_7_pro`	412×892	3.5	Google Pixel 7 Pro
`samsung_galaxy_s21`	360×800	3	Samsung Galaxy S21
`samsung_galaxy_s23`	360×780	3	Samsung Galaxy S23
`galaxy_tab_s7`	800×1280	2	Samsung Galaxy Tab S7
`surface_pro_7`	912×1368	2	Microsoft Surface Pro 7

Optimized dimensions for social platforms:

Preset	Dimensions	Description
`facebook_og`	1200×630	Facebook Open Graph
`twitter_card`	1200×675	Twitter/X Card
`linkedin_post`	1200×627	LinkedIn Post
`instagram_square`	1080×1080	Instagram Square
`instagram_portrait`	1080×1350	Instagram Portrait
`instagram_story`	1080×1920	Instagram Story

Examples

Mobile screenshot

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "device": "iphone_15"
  }' --output mobile.png

Retina desktop

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "viewport": {
      "width": 1920,
      "height": 1080,
      "deviceScaleFactor": 2
    }
  }' --output retina.png

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "device": "twitter_card"
  }' --output og-image.png

Responsive comparison

Use composition to capture multiple devices:

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

Full page screenshots

Capture the entire scrollable page:

{
  "url": "https://example.com",
  "fullPage": true,
  "viewport": {
    "width": 1920,
    "height": 1080
  }
}

For full page captures, the height in viewport only sets the initial viewport. The final image height matches the page content.

Best practices

Match your target audience

Use device presets that match your users' devices:

// Analytics shows 60% mobile traffic
const mobileScreenshot = await capture({
  url: 'https://example.com',
  device: 'iphone_15',
});

Use appropriate DPR

Higher DPR produces sharper images but larger files:

Use case	Recommended DPR
Thumbnails	1
Documentation	1-2
Marketing	2
Print	2-3

Consider aspect ratios

Social platforms have specific requirements:

// Twitter/X card
const twitterCard = await capture({
  url: 'https://example.com',
  device: 'twitter_card', // 1200×675 (16:9)
});

// Instagram
const instagramSquare = await capture({
  url: 'https://example.com',
  device: 'instagram_square', // 1080×1080 (1:1)
});

Viewport and devices

On this page