Shotbot Screenshot API (2)

Named output preset. When set, fills missing viewport_width, output_size, and crop_height with the preset's defaults. Explicit values still win over preset defaults.

Omit preset (or pass "") for a 1280px viewport with the browser default height; preset=laptop pins that to an explicit 1280×800 (16:10). crop_height from a preset is always accepted (otherwise Pro-only).

Browser viewport width in pixels. Default: 1280. Common labelled widths: 360, 375, 390, 414, 430, 768, 1024, 1200, 1280, 1440, 1920. Non-Pro accounts are limited to 390, 768, 1280. Shotbot Pro may also pass any custom width between 280 and 3840 px, useful for CSS / responsive testing at arbitrary breakpoints. A value outside the allowed set returns 400 invalid_viewport_width. Filled automatically when preset is set and this field is omitted.

Output image width in pixels. Defaults to viewport_width when omitted. Values not in the enum are replaced with viewport_width. Filled automatically when preset is set and this field is omitted.

Aspect ratio used to compute output height. An empty string falls back to the default; a non-empty value outside the enum returns 400 invalid_ratio. Ignored when fullpage is true, crop_height is set, or selector is used.

Custom output height in pixels. Overrides ratio. Sets the viewport height and captures that region from the top of the page (not a full-page capture, so bottom-anchored fixed/sticky elements render at the bottom). Maximum: 30,000 px. Pro only when set explicitly. Free accounts can use it via the preset parameter (e.g. preset=og provides crop_height=630 without Pro).

Capture the full page height (max 30,000 px). Ignores ratio.

Output format. Non-Pro accounts are limited to jpg.

Render at 2× device pixel ratio (HiDPI / Retina).

Force a color scheme before capture. "dark" emits prefers-color-scheme: dark, "light" emits prefers-color-scheme: light. Omit (or pass null) to use the browser default.

Geographic region the rendering worker exits from. The browser is routed through a SOCKS5 proxy in the chosen region and its locale, timezone, and geolocation are emulated to match.

Region key shape: country-city (ISO 3166 alpha-2 country code, then city name, dash-separated; multi-word cities use dashes too).

Use to capture geo-restricted content, regionally localised pages, currency or banner variants, or to verify what a page looks like from a given market. Pro only for non-fr-paris values; non-Pro accounts may omit the field or pass "fr-paris".

Disable JavaScript execution before capture.

Launch Chromium with --autoplay-policy=no-user-gesture-required so <video autoplay> elements start playing (including unmuted videos) without requiring a user gesture. Useful for capturing pages with hero videos that would otherwise show a static poster frame. Default Chromium policy blocks unmuted autoplay; this flag overrides it.

No effect on PDF captures (no playback) or when the page itself has no <video autoplay>. Pro only.

Emulate the prefers-reduced-motion: reduce CSS media feature. Well-built sites use this to skip or shorten their animations (framer-motion, GSAP, AOS, IntersectionObserver reveals), which makes captures cleaner | no half-played transitions, no mid-animation frames. No effect on sites that don't honour the media query. Available to all accounts.

Render with a transparent background (omitBackground: true on the underlying Chromium screenshot). The page's own background colour is preserved; only the default white viewport backdrop becomes transparent. Useful when capturing components or pages designed to sit on a host page's background.

Visible on png / webp / avif. jpg has no alpha channel so transparency flattens to black on conversion (silent no-op). Has no effect on PDF output. Pro only.

Call page.emulateMediaType('print') before capture so the page renders with its print stylesheet (@media print rules apply). Useful for capturing print-only layouts as an image. Has no additional effect on PDF output (PDFs already render in print mode). Pro only.

Seconds to wait after page load before capturing (0 = capture immediately after page load). Free accounts: 0-5. Shotbot Pro: 0-30 (longer waits help JavaScript-heavy / slow pages). A free request above 5 s is rejected with pro_required (or clamped to 5 s on the wait_time alias path). Alias: wait (accepted for backward compatibility).

Auto-interact with cookie consent banners. Pro only. "" (default) = leave the banner visible, "accept" = click accept, "reject" = click reject.

Decorative frame composited around the rendered image (image formats only, silently ignored for PDF).

Most variants extend OUTSIDE the requested output_size (final image is larger by ~20-100 px depending on variant). rounded is the exception | dimensions stay the same, only the corner pixels are clipped. Padding around shadow/shotbot_brand is edge-sampled from the rendered image so dark themes get dark padding.

Free accounts get a small shotbot.fr / shotbot.net wordmark on any non-empty frame (domain picked per the captured page's language). For shotbot_brand the wordmark is integrated into the bottom-right bracket itself rather than overlaid. Pro accounts get a clean frame on ALL variants, including shotbot_brand (brackets only, no wordmark). No Pro gating on the choice of variant itself | all values are available to everyone.

PNG/WebP/AVIF formats render transparent pixels outside the mockup bezel (real see-through corners). JPG has no alpha channel so those areas flatten to black.

Scroll the page before capturing (triggers lazy-loaded images). Pro only.

Scroll the page down by this many pixels before capturing (no scroll back), so the viewport frame starts at Y=N. Runs after scroll_before_capture. Mutually exclusive with scroll_to (sending both returns 400 invalid_scroll_combo). No-op for fullpage, PDF, and selector captures. Out of range returns 400 invalid_scroll_offset. Not available on the web form. Pro only.

CSS selector to scrollIntoView before capturing, so the matched element sits at the top of the viewport frame. Unlike selector (which clips output to the element), scroll_to only positions the page, then captures the normal viewport. Runs after scroll_before_capture. Mutually exclusive with scroll_offset_px (400 invalid_scroll_combo). If the selector matches no element it is a no-op (the job still succeeds). No-op for fullpage, PDF, and selector captures. Not available on the web form. Pro only.

Block ad network requests during capture. Pro only.

HTTP Basic Auth credentials for password-protected pages. Pro only.

PDF page size. Only used when format is pdf.

PDF page margin in mm. Only used when format is pdf.

PDF rendering scale factor. Only used when format is pdf.

PDF landscape orientation. Only used when format is pdf.

CSS selector of the DOM element to screenshot. Only the matched element is captured, returned at its natural dimensions: output_size, output_height, ratio and crop_height are not applied (the element is not re-cropped or re-scaled). Ignored when format is pdf. The job fails with nav_error if the selector matches no element or if the matched element exceeds 30,000 px in height. Not available on the web form. Pro only.

Private capture. When true, the result is not uploaded to static.shotbot.net. Instead, the response from GET /capture/{token} includes a download URL pointing at https://api.shotbot.net/capture/{token}/file, which streams the bytes. The file is not deleted on read: you can fetch it as many times as you like until it auto-expires after a short retention window. There is no public CDN URL.

The web preview ({token}_p.webp) is also skipped - the response has no preview field for private captures.

Deduplication is disabled for private captures (each call produces a fresh token with its own file).

Available to all accounts (not Pro-gated).

Cookies to inject before navigation. Useful for capturing authenticated pages without HTTP Basic Auth. Each entry must include name and value. If domain is omitted, the cookie is scoped to the target URL's domain. Maximum 50 cookies. Pro only.

Your 12-character alphanumeric API key.

Named output preset. When set, fills missing viewport_width, output_size, and crop_height with the preset's defaults. Explicit values still win over preset defaults.

Omit preset (or pass "") for a 1280px viewport with the browser default height; preset=laptop pins that to an explicit 1280×800 (16:10). crop_height from a preset is always accepted (otherwise Pro-only).

Browser viewport width in pixels. Default: 1280. Common labelled widths: 360, 375, 390, 414, 430, 768, 1024, 1200, 1280, 1440, 1920. Non-Pro accounts are limited to 390, 768, 1280. Shotbot Pro may also pass any custom width between 280 and 3840 px, useful for CSS / responsive testing at arbitrary breakpoints. A value outside the allowed set returns 400 invalid_viewport_width. Filled automatically when preset is set and this field is omitted.

Output image width in pixels. Defaults to viewport_width when omitted. Values not in the enum are replaced with viewport_width. Filled automatically when preset is set and this field is omitted.

Aspect ratio used to compute output height. An empty string falls back to the default; a non-empty value outside the enum returns 400 invalid_ratio. Ignored when fullpage is true, crop_height is set, or selector is used.

Custom output height in pixels. Overrides ratio. Sets the viewport height and captures that region from the top of the page (not a full-page capture, so bottom-anchored fixed/sticky elements render at the bottom). Maximum: 30,000 px. Pro only when set explicitly. Free accounts can use it via the preset parameter (e.g. preset=og provides crop_height=630 without Pro).

Capture the full page height (max 30,000 px). Ignores ratio.

Output format. Non-Pro accounts are limited to jpg.

Render at 2× device pixel ratio (HiDPI / Retina).

Force a color scheme before capture. "dark" emits prefers-color-scheme: dark, "light" emits prefers-color-scheme: light. Omit (or pass null) to use the browser default.

Geographic region the rendering worker exits from. The browser is routed through a SOCKS5 proxy in the chosen region and its locale, timezone, and geolocation are emulated to match.

Region key shape: country-city (ISO 3166 alpha-2 country code, then city name, dash-separated; multi-word cities use dashes too).

Use to capture geo-restricted content, regionally localised pages, currency or banner variants, or to verify what a page looks like from a given market. Pro only for non-fr-paris values; non-Pro accounts may omit the field or pass "fr-paris".

Disable JavaScript execution before capture.

Launch Chromium with --autoplay-policy=no-user-gesture-required so <video autoplay> elements start playing (including unmuted videos) without requiring a user gesture. Useful for capturing pages with hero videos that would otherwise show a static poster frame. Default Chromium policy blocks unmuted autoplay; this flag overrides it.

No effect on PDF captures (no playback) or when the page itself has no <video autoplay>. Pro only.

Emulate the prefers-reduced-motion: reduce CSS media feature. Well-built sites use this to skip or shorten their animations (framer-motion, GSAP, AOS, IntersectionObserver reveals), which makes captures cleaner | no half-played transitions, no mid-animation frames. No effect on sites that don't honour the media query. Available to all accounts.

Render with a transparent background (omitBackground: true on the underlying Chromium screenshot). The page's own background colour is preserved; only the default white viewport backdrop becomes transparent. Useful when capturing components or pages designed to sit on a host page's background.

Visible on png / webp / avif. jpg has no alpha channel so transparency flattens to black on conversion (silent no-op). Has no effect on PDF output. Pro only.

Call page.emulateMediaType('print') before capture so the page renders with its print stylesheet (@media print rules apply). Useful for capturing print-only layouts as an image. Has no additional effect on PDF output (PDFs already render in print mode). Pro only.

Seconds to wait after page load before capturing (0 = capture immediately after page load). Free accounts: 0-5. Shotbot Pro: 0-30 (longer waits help JavaScript-heavy / slow pages). A free request above 5 s is rejected with pro_required (or clamped to 5 s on the wait_time alias path). Alias: wait (accepted for backward compatibility).

Auto-interact with cookie consent banners. Pro only. "" (default) = leave the banner visible, "accept" = click accept, "reject" = click reject.

Decorative frame composited around the rendered image (image formats only, silently ignored for PDF).

Most variants extend OUTSIDE the requested output_size (final image is larger by ~20-100 px depending on variant). rounded is the exception | dimensions stay the same, only the corner pixels are clipped. Padding around shadow/shotbot_brand is edge-sampled from the rendered image so dark themes get dark padding.

Free accounts get a small shotbot.fr / shotbot.net wordmark on any non-empty frame (domain picked per the captured page's language). For shotbot_brand the wordmark is integrated into the bottom-right bracket itself rather than overlaid. Pro accounts get a clean frame on ALL variants, including shotbot_brand (brackets only, no wordmark). No Pro gating on the choice of variant itself | all values are available to everyone.

PNG/WebP/AVIF formats render transparent pixels outside the mockup bezel (real see-through corners). JPG has no alpha channel so those areas flatten to black.

Scroll the page before capturing (triggers lazy-loaded images). Pro only.

Scroll the page down by this many pixels before capturing (no scroll back), so the viewport frame starts at Y=N. Runs after scroll_before_capture. Mutually exclusive with scroll_to (sending both returns 400 invalid_scroll_combo). No-op for fullpage, PDF, and selector captures. Out of range returns 400 invalid_scroll_offset. Not available on the web form. Pro only.

CSS selector to scrollIntoView before capturing, so the matched element sits at the top of the viewport frame. Unlike selector (which clips output to the element), scroll_to only positions the page, then captures the normal viewport. Runs after scroll_before_capture. Mutually exclusive with scroll_offset_px (400 invalid_scroll_combo). If the selector matches no element it is a no-op (the job still succeeds). No-op for fullpage, PDF, and selector captures. Not available on the web form. Pro only.

Block ad network requests during capture. Pro only.

HTTP Basic Auth credentials for password-protected pages. Pro only.

PDF page size. Only used when format is pdf.

PDF page margin in mm. Only used when format is pdf.

PDF rendering scale factor. Only used when format is pdf.

PDF landscape orientation. Only used when format is pdf.

CSS selector of the DOM element to screenshot. Only the matched element is captured, returned at its natural dimensions: output_size, output_height, ratio and crop_height are not applied (the element is not re-cropped or re-scaled). Ignored when format is pdf. The job fails with nav_error if the selector matches no element or if the matched element exceeds 30,000 px in height. Not available on the web form. Pro only.

Private capture. When true, the result is not uploaded to static.shotbot.net. Instead, the response from GET /capture/{token} includes a download URL pointing at https://api.shotbot.net/capture/{token}/file, which streams the bytes. The file is not deleted on read: you can fetch it as many times as you like until it auto-expires after a short retention window. There is no public CDN URL.

The web preview ({token}_p.webp) is also skipped - the response has no preview field for private captures.

Deduplication is disabled for private captures (each call produces a fresh token with its own file).

Available to all accounts (not Pro-gated).

Cookies to inject before navigation. Useful for capturing authenticated pages without HTTP Basic Auth. Each entry must include name and value. If domain is omitted, the cookie is scoped to the target URL's domain. Maximum 50 cookies. Pro only.

Your 12-character alphanumeric API key.

Target URL. Must be a public http/https URL (no private IPs, no localhost). URLs with a non-standard TCP port (e.g. http://test.shotbot.net:8080/) require a Pro subscription; submitting one without Pro returns 403 pro_required with fields: ["url"].

HTTPS endpoint where Shotbot will POST the result (multipart image). Must use HTTPS and resolve to a public IP address.

Named output preset. When set, fills missing viewport_width, output_size, and crop_height with the preset's defaults. Explicit values still win over preset defaults.

Omit preset (or pass "") for a 1280px viewport with the browser default height; preset=laptop pins that to an explicit 1280×800 (16:10). crop_height from a preset is always accepted (otherwise Pro-only).

Browser viewport width in pixels. Default: 1280. Common labelled widths: 360, 375, 390, 414, 430, 768, 1024, 1200, 1280, 1440, 1920. Non-Pro accounts are limited to 390, 768, 1280. Shotbot Pro may also pass any custom width between 280 and 3840 px, useful for CSS / responsive testing at arbitrary breakpoints. A value outside the allowed set returns 400 invalid_viewport_width. Filled automatically when preset is set and this field is omitted.

Output image width in pixels. Defaults to viewport_width when omitted. Values not in the enum are replaced with viewport_width. Filled automatically when preset is set and this field is omitted.

Aspect ratio used to compute output height. An empty string falls back to the default; a non-empty value outside the enum returns 400 invalid_ratio. Ignored when fullpage is true, crop_height is set, or selector is used.

Custom output height in pixels. Overrides ratio. Sets the viewport height and captures that region from the top of the page (not a full-page capture, so bottom-anchored fixed/sticky elements render at the bottom). Maximum: 30,000 px. Pro only when set explicitly. Free accounts can use it via the preset parameter (e.g. preset=og provides crop_height=630 without Pro).

Capture the full page height (max 30,000 px). Ignores ratio.

Output format. Non-Pro accounts are limited to jpg.

Render at 2× device pixel ratio (HiDPI / Retina).

Force a color scheme before capture. "dark" emits prefers-color-scheme: dark, "light" emits prefers-color-scheme: light. Omit (or pass null) to use the browser default.

Geographic region the rendering worker exits from. The browser is routed through a SOCKS5 proxy in the chosen region and its locale, timezone, and geolocation are emulated to match.

Region key shape: country-city (ISO 3166 alpha-2 country code, then city name, dash-separated; multi-word cities use dashes too).

Use to capture geo-restricted content, regionally localised pages, currency or banner variants, or to verify what a page looks like from a given market. Pro only for non-fr-paris values; non-Pro accounts may omit the field or pass "fr-paris".

Disable JavaScript execution before capture.

Launch Chromium with --autoplay-policy=no-user-gesture-required so <video autoplay> elements start playing (including unmuted videos) without requiring a user gesture. Useful for capturing pages with hero videos that would otherwise show a static poster frame. Default Chromium policy blocks unmuted autoplay; this flag overrides it.

No effect on PDF captures (no playback) or when the page itself has no <video autoplay>. Pro only.

Emulate the prefers-reduced-motion: reduce CSS media feature. Well-built sites use this to skip or shorten their animations (framer-motion, GSAP, AOS, IntersectionObserver reveals), which makes captures cleaner | no half-played transitions, no mid-animation frames. No effect on sites that don't honour the media query. Available to all accounts.

Render with a transparent background (omitBackground: true on the underlying Chromium screenshot). The page's own background colour is preserved; only the default white viewport backdrop becomes transparent. Useful when capturing components or pages designed to sit on a host page's background.

Visible on png / webp / avif. jpg has no alpha channel so transparency flattens to black on conversion (silent no-op). Has no effect on PDF output. Pro only.

Call page.emulateMediaType('print') before capture so the page renders with its print stylesheet (@media print rules apply). Useful for capturing print-only layouts as an image. Has no additional effect on PDF output (PDFs already render in print mode). Pro only.

Seconds to wait after page load before capturing (0 = capture immediately after page load). Free accounts: 0-5. Shotbot Pro: 0-30 (longer waits help JavaScript-heavy / slow pages). A free request above 5 s is rejected with pro_required (or clamped to 5 s on the wait_time alias path). Alias: wait (accepted for backward compatibility).

Auto-interact with cookie consent banners. Pro only. "" (default) = leave the banner visible, "accept" = click accept, "reject" = click reject.

Decorative frame composited around the rendered image (image formats only, silently ignored for PDF).

Most variants extend OUTSIDE the requested output_size (final image is larger by ~20-100 px depending on variant). rounded is the exception | dimensions stay the same, only the corner pixels are clipped. Padding around shadow/shotbot_brand is edge-sampled from the rendered image so dark themes get dark padding.

Free accounts get a small shotbot.fr / shotbot.net wordmark on any non-empty frame (domain picked per the captured page's language). For shotbot_brand the wordmark is integrated into the bottom-right bracket itself rather than overlaid. Pro accounts get a clean frame on ALL variants, including shotbot_brand (brackets only, no wordmark). No Pro gating on the choice of variant itself | all values are available to everyone.

PNG/WebP/AVIF formats render transparent pixels outside the mockup bezel (real see-through corners). JPG has no alpha channel so those areas flatten to black.

Scroll the page before capturing (triggers lazy-loaded images). Pro only.

Scroll the page down by this many pixels before capturing (no scroll back), so the viewport frame starts at Y=N. Runs after scroll_before_capture. Mutually exclusive with scroll_to (sending both returns 400 invalid_scroll_combo). No-op for fullpage, PDF, and selector captures. Out of range returns 400 invalid_scroll_offset. Not available on the web form. Pro only.

CSS selector to scrollIntoView before capturing, so the matched element sits at the top of the viewport frame. Unlike selector (which clips output to the element), scroll_to only positions the page, then captures the normal viewport. Runs after scroll_before_capture. Mutually exclusive with scroll_offset_px (400 invalid_scroll_combo). If the selector matches no element it is a no-op (the job still succeeds). No-op for fullpage, PDF, and selector captures. Not available on the web form. Pro only.

Block ad network requests during capture. Pro only.

HTTP Basic Auth credentials for password-protected pages. Pro only.

PDF page size. Only used when format is pdf.

PDF page margin in mm. Only used when format is pdf.

PDF rendering scale factor. Only used when format is pdf.

PDF landscape orientation. Only used when format is pdf.

CSS selector of the DOM element to screenshot. Only the matched element is captured, returned at its natural dimensions: output_size, output_height, ratio and crop_height are not applied (the element is not re-cropped or re-scaled). Ignored when format is pdf. The job fails with nav_error if the selector matches no element or if the matched element exceeds 30,000 px in height. Not available on the web form. Pro only.

Private capture. When true, the result is not uploaded to static.shotbot.net. Instead, the response from GET /capture/{token} includes a download URL pointing at https://api.shotbot.net/capture/{token}/file, which streams the bytes. The file is not deleted on read: you can fetch it as many times as you like until it auto-expires after a short retention window. There is no public CDN URL.

The web preview ({token}_p.webp) is also skipped - the response has no preview field for private captures.

Deduplication is disabled for private captures (each call produces a fresh token with its own file).

Available to all accounts (not Pro-gated).

Cookies to inject before navigation. Useful for capturing authenticated pages without HTTP Basic Auth. Each entry must include name and value. If domain is omitted, the cookie is scoped to the target URL's domain. Maximum 50 cookies. Pro only.

Your 12-character alphanumeric API key.

Array of capture jobs. Each entry must include a url and may override any global option. Non-Pro accounts are limited to their batch_limit (default 500); Pro accounts may submit up to 5000.

Global webhook URL. When set, all jobs in the batch become callback jobs. Must use HTTPS and resolve to a public IP.

Global HMAC secret echoed back in every callback POST.