GET /screenshot/create — Documentation API

← Retour à l’index API

GET /screenshot/create

Request a screenshot

Options

Les options sont regroupées pour faciliter la lecture, sur le modèle d’une documentation centrée sur les paramètres.

Essential

`browser`

query enum(chrome, firefox, brave) Facultatif

Exemple : chrome

Browser to use for screenshot (chrome, firefox, or brave)

`country`

query string Facultatif

Exemple : us

ISO 3166-1 alpha-2 country code for IP geolocation. Defaults to "us" when omitted.

Two-letter country code for routing the browser through a target country. Use this when validating localization, legal notices, pricing, and geo-specific rendering.

`delay`

query integer Facultatif

Exemple : 5

Seconds to wait after page load for JavaScript execution

`hide_ads`

query boolean Facultatif

Exemple : false

Block ads using network filtering (disabled for Brave)

Enable ad filtering for cleaner captures and visual diffs. On some browser targets, behavior may vary depending on native filtering support.

`hide_popups`

query boolean Facultatif

Exemple : false

Hide popups and overlays

Attempt to hide cookie banners and popup overlays before capture so outputs focus on page content.

`screen_height`

query integer Facultatif

Exemple : 1280

Browser viewport height in pixels

`screen_width`

query integer Facultatif

Exemple : 1024

Browser viewport width in pixels

`size`

query enum(screen, page) Facultatif

Exemple : screen

Screenshot size mode: viewport ('screen') or full page ('page')

`url`

query string Obligatoire

URL of the page to screenshot.

Request

`cookie`

query string Facultatif

Cookies as semicolon-separated key=value pairs

`header`

query string[] Facultatif

Custom HTTP headers. Each item should be a JSON object string. Can specify multiple header sets.

`post_data`

query string Facultatif

POST data for form submission (URL-encoded)

`referer`

query string Facultatif

Custom HTTP Referer header

`user_agent`

query string Facultatif

Custom User-Agent header to use for HTTP requests

Browser

`dark`

query boolean Facultatif

Exemple : false

Enable dark mode rendering

`strict_ssl`

query boolean Facultatif

Exemple : false

Enforce strict SSL certificate validation

Automation

`step`

query object[] Facultatif

Alternative steps array notation (step[0][command], step[0][value], etc.). Cannot be used with steps.

`steps`

query object[] Facultatif

Array of automation commands to execute before/after screenshot

JSON-encoded automation steps executed before capture. Use steps to click, type, wait, scroll, and stabilize dynamic UIs before image/PDF/video output is generated.

Screenshot

`cache`

query integer Facultatif

Exemple : 86400

Cache duration in seconds. 0 = always fresh, 86400 = 24 hours

`shot_interval`

query integer Facultatif

Exemple : 5

Seconds between sequential shots

`shots`

query integer Facultatif

Exemple : 1

Number of sequential screenshots

`tag`

query string[] Facultatif

Tags for organizing screenshots. Can specify multiple tags as tag=one&tag=two or comma-separated as tag=one,two

`target`

query string Facultatif

CSS selector. If provided, take a screenshot of the element. If not found within 30 seconds or max_wait, fall back to page/window screenshot.

CSS selector of the element to capture. If provided, capture is scoped to the matched element instead of the full viewport/page.

PDF Options

`pdf`

query boolean Facultatif

Exemple : false

Save rendered PDF

Set to true to generate a PDF artifact in addition to the screenshot. Retrieve the output later from the PDF endpoint.

`pdf_background`

query boolean Facultatif

Exemple : false

Include background graphics in PDF

`pdf_format`

query enum(a4, letter, legal) Facultatif

Exemple : letter

PDF paper format

`pdf_landscape`

query boolean Facultatif

Exemple : false

Render PDF in landscape mode

`pdf_margin`

query string Facultatif

Exemple : 20px

Default PDF margin applied to all sides — any CSS unit: px, mm, in, cm. Overridden per-side by pdf_margin_top/right/bottom/left.

`pdf_margin_bottom`

query string Facultatif

Exemple : 20px

Bottom margin — any CSS unit.

`pdf_margin_left`

query string Facultatif

Exemple : 20px

Left margin — any CSS unit.

`pdf_margin_right`

query string Facultatif

Exemple : 20px

Right margin — any CSS unit.

`pdf_margin_top`

query string Facultatif

Exemple : 20px

Top margin — any CSS unit: px, mm, in, cm.

`pdf_one_page`

query boolean Facultatif

Exemple : false

Fit rendered page on a single PDF page

Video Options

`video`

query boolean Facultatif

Exemple : false

Save a screencast video of the page loading

Set to true to generate a video recording of the page flow. Combine with `video_format`, `video_quality`, and `video_speed` for control over output.

`video_colors`

query integer Facultatif

Number of palette colors for GIF output (2-256). Fewer colors produce smaller files with some quality loss. Has no effect on WebM/MP4.

Number of palette colors used in GIF output (2–256). Reducing the palette shrinks file size with some quality trade-off. Has no effect on WebM or MP4 output.

`video_duration`

query integer Facultatif

Exemple : 15

Screencast recording duration in seconds (0 = no minimum recording time)

`video_format`

query enum(webm, mp4, gif) Facultatif

Exemple : webm

Screencast output format

`video_fps`

query integer Facultatif

Screencast frame rate (frames per second). Defaults to 20 for GIF, 30 for WebM/MP4. Lower values produce smaller GIF files.

Frame rate for the video recording. Defaults to 20 fps for GIF and 30 fps for WebM/MP4. Lower values produce smaller GIF files at the cost of smoothness.

`video_quality`

query integer Facultatif

Exemple : 30

Screencast quality (0-63, lower is better quality)

`video_scale`

query number Facultatif

Scale factor applied to the output video dimensions (0.1-1.0). For example, 0.5 halves both width and height, reducing file size by ~75%.

Scale factor applied to the output video dimensions (0.1–1.0). A value of 0.5 halves both width and height, reducing file size by roughly 75%.

`video_speed`

query number Facultatif

Exemple : 1

Screencast playback speed multiplier

App

`apps`

query any Facultatif

Apps to run after the screenshot is finished. You can pass a list of app IDs, for example `apps=google-drive&apps=dropbox`, or a deep object that maps each app ID to an optional path or filename template override, for example `apps[google-drive]=` or `apps[google-drive]={yyyy}/{mm}/{dd}/{domain}.png`.

Output & Format

`html`

query boolean Facultatif

Exemple : false

Save rendered HTML

Geolocation

`geo_enable`

query boolean Facultatif

Exemple : false

Enable geolocation emulation in the browser for this request

`geo_latitude`

query number Facultatif

Override latitude for geolocation (decimal degrees)

`geo_longitude`

query number Facultatif

Override longitude for geolocation (decimal degrees)

`language`

query string Facultatif

Override language/locale for the screenshot job (e.g., en-US, fr-FR)

`timezone`

query string Facultatif

Override timezone for geolocation (e.g., America/New_York)

Device

`device_landscape`

query boolean Facultatif

Use landscape orientation for device emulation (used with screen_width/screen_height when device_name is not set)

`device_mobile`

query boolean Facultatif

Enable mobile emulation (used with screen_width/screen_height when device_name is not set)

`device_name`

query string Facultatif

Device name to emulate (e.g., iphone_15_pro or iphone_15_pro_landscape). If provided and found, other device_* parameters are ignored.

Named device profile for viewport and input emulation. Prefer this when reproducing mobile/tablet rendering for specific real-world devices.

`device_scale`

query number Facultatif

Device scale factor (used with screen_width/screen_height when device_name is not set)

`device_touch`

query boolean Facultatif

Enable touch input for device emulation (used with screen_width/screen_height when device_name is not set)

Réponses

200

Screenshot request accepted

▾

{
  "success": true,
  "data": {
    "id": 12345678,
    "status": "processing",
    "url": "https://example.com",
    "final_url": "https://example.com",
    "response_code": null,
    "cost": 1,
    "tag": [],
    "created_at": "2026-02-06T05:34:02.730Z",
    "finished_at": "",
    "country": "us",
    "region": "America",
    "language": "en-US",
    "timezone": "America/New_York",
    "geo_enable": false,
    "geo_latitude": 40.7128,
    "geo_longitude": -74.006,
    "size": "screen",
    "cache": 86400,
    "delay": 5,
    "screen_width": 1024,
    "screen_height": 1280,
    "priority": 2,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "script": "",
    "html": false,
    "pdf": false,
    "pdf_background": false,
    "pdf_one_page": false,
    "pdf_landscape": false,
    "pdf_format": "letter",
    "pdf_margin": "0px",
    "pdf_margin_top": "0px",
    "pdf_margin_bottom": "0px",
    "pdf_margin_left": "0px",
    "pdf_margin_right": "0px",
    "video": false,
    "video_format": "webm",
    "video_quality": 30,
    "video_speed": 1,
    "video_duration": 15,
    "video_fps": null,
    "video_colors": null,
    "video_scale": null,
    "max_wait": 0,
    "header": "",
    "hide_popups": false,
    "hide_ads": false,
    "dark": false,
    "shots": 1,
    "shot_interval": 5,
    "strict_ssl": false,
    "target": "",
    "device_name": "",
    "device_scale": 3,
    "device_touch": true,
    "device_landscape": false
  }
}

400

Invalid request parameters

▾

{
  "error": "Request validation failed",
  "code": "VALIDATION_ERROR",
  "fields": {
    "url": [
      "URL is required"
    ],
    "country": [
      "Country code must be ISO 3166-1 alpha-2"
    ]
  }
}

401

Invalid or missing API key

▾

{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "request_id": "req_123456"
  }
}

403

Insufficient balance or account limitations

▾

{
  "error": "Insufficient credit balance",
  "status": "error",
  "code": "INSUFFICIENT_BALANCE"
}

429

Rate limit exceeded

▾

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}

500

Server error

▾

{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "request_id": "req_123456"
  }
}

503

Service temporarily unavailable

▾

{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "request_id": "req_123456"
  }
}

Options

Essential

browser

country

delay

hide_ads

hide_popups

screen_height

screen_width

size

url

Request

cookie

header

post_data

referer

user_agent

Page

max_wait

script

script_inline

tracker

trackers

Browser

dark

strict_ssl

Automation

step

steps

Screenshot

cache

shot_interval

shots

tag

target

PDF Options

pdf

pdf_background

pdf_format

pdf_landscape

pdf_margin

pdf_margin_bottom

pdf_margin_left

pdf_margin_right

pdf_margin_top

pdf_one_page

Video Options

video

video_colors

video_duration

video_format

video_fps

video_quality

video_scale

video_speed

App

apps

Output & Format

html

Geolocation

geo_enable

geo_latitude

geo_longitude

language

timezone

Device

device_landscape

device_mobile

device_name

device_scale

device_touch

Réponses

`browser`

`country`

`delay`

`hide_ads`

`hide_popups`

`screen_height`

`screen_width`

`size`

`url`

`cookie`

`header`

`post_data`

`referer`

`user_agent`

`max_wait`

`script`

`script_inline`

`tracker`

`trackers`

`dark`

`strict_ssl`

`step`

`steps`

`cache`

`shot_interval`

`shots`

`tag`

`target`

`pdf`

`pdf_background`

`pdf_format`

`pdf_landscape`

`pdf_margin`

`pdf_margin_bottom`

`pdf_margin_left`

`pdf_margin_right`

`pdf_margin_top`

`pdf_one_page`

`video`

`video_colors`

`video_duration`

`video_format`

`video_fps`

`video_quality`

`video_scale`

`video_speed`

`apps`

`html`

`geo_enable`

`geo_latitude`

`geo_longitude`

`language`

`timezone`

`device_landscape`

`device_mobile`

`device_name`

`device_scale`

`device_touch`