Build your integration
Screenshot API parameter reference
Compare GET and POST options for screenshots, PDF, WebM video, viewport sizes, CSS selectors, delays, watermarking, and cache control.
View as MarkdownEndpoint and request methods
Use GET or POST at https://api.screenshotengine.com/v1/screenshot. GET accepts query strings. POST accepts a JSON body with Content-Type: application/json and a Bearer API key.
Parameter names are case-sensitive. GET uses snake_case for options such as block_banners; POST uses camelCase such as blockBanners. Send actual booleans and numbers in JSON.
Capture options
Only url is required in the POST body. GET also requires api_key. The table lists the default behavior when an option is omitted.
| POST field | GET parameter | Values and behavior |
|---|---|---|
| url | url | Required. An absolute, publicly reachable HTTP or HTTPS URL. |
| output | output | image (default), pdf, or scrolling_video. |
| format | format | jpeg (default), png, or webp. Controls image output only. |
| width | width | 1280 by default. GET validates 100–3840 pixels; use this range for POST too. |
| height | height | 720 by default. A viewport height or "full" for full-page capture. GET validates numeric heights of 100–10000 pixels. |
| blockBanners | block_banners | false by default. Set true to attempt cookie banner and consent-dialog removal. |
| darkMode | dark_mode | false by default. Set true to request the target website’s dark color scheme. |
| viewportDevice | viewport_device | Optional preset name from the list below. Overrides viewport width and height. |
| selector | selector | Optional CSS selector, at most 200 characters. Captures the first matching element for an image. |
| waitFor | wait_for | Optional delay after page load, in milliseconds. Use 0–30000. GET rejects values outside this range; the engine skips out-of-range POST delays. |
| cachePolicy | Not available | default or no-cache. POST only. no-cache bypasses cache reads and writes. |
| watermark | Not available | POST-only object for image watermarks. See fields below. |
| pdfSettings.paperSize | pdf_paper_size | A4 (default), Letter, Legal, Tabloid, A3, or A5. Only for output=pdf. |
| pdfSettings.orientation | pdf_orientation | portrait (default) or landscape. Only for output=pdf. |
Available viewport presets
Presets set the browser viewport dimensions. They do not emulate a physical device’s browser, touch input, user agent, or pixel density. To capture a full page at a specific mobile width, send width and height: "full" without a preset.
| Preset | Width × height (CSS pixels) |
|---|---|
| desktop-1080p | 1920 × 1080 |
| desktop-720p | 1280 × 720 |
| desktop-4k | 3840 × 2160 |
| macbook-pro-16 | 1728 × 1117 |
| macbook-pro-14 | 1512 × 982 |
| macbook-air-13 | 1470 × 956 |
| iphone-15-pro-max | 430 × 932 |
| iphone-15-pro | 393 × 852 |
| iphone-15 | 393 × 852 |
| iphone-14 | 390 × 844 |
| iphone-se | 375 × 667 |
| ipad-pro-12.9 | 1024 × 1366 |
| ipad-pro-11 | 834 × 1194 |
| ipad-air | 820 × 1180 |
| ipad-mini | 768 × 1024 |
| pixel-8-pro | 448 × 998 |
| pixel-8 | 412 × 915 |
| samsung-galaxy-s24 | 360 × 780 |
| samsung-galaxy-s24-ultra | 412 × 915 |
| samsung-galaxy-tab-s9 | 800 × 1280 |
Watermark object
Use watermark with image output. Do not combine it with PDF or scrolling video. Set text to a string of 1–100 characters.
| Field | Default | Accepted values |
|---|---|---|
| text | Required | 1–100 characters |
| position | bottom-right | top-left, top-middle, top-right, middle-left, center, middle-right, bottom-left, bottom-center, bottom-right |
| textColor | White | White, Black, Red, Blue (case-sensitive) |
| backgroundColor | Black | White, Black, Red, Blue (case-sensitive) |
Response content types
Successful requests return HTTP 200 and raw file bytes. Read Content-Type to identify the result; do not call response.json() on a successful capture.
| Output | Content-Type | Extension |
|---|---|---|
| JPEG image | image/jpeg | .jpg |
| PNG image | image/png | .png |
| WebP image | image/webp | .webp |
| PDF document | application/pdf | |
| Scrolling video | video/webm | .webm |