SCscreenshotone

Record a video or an animated GIF of a website, HTML, or Markdown

Changed on

Record a short video or an animated GIF of a website by its URL, or of the rendered HTML or Markdown, optionally scrolling the page.

post/animate

Request

Request body

access_keystring
urlstring uri

The URL of the site to render. One of url, html or markdown is required.

htmlstring

The HTML to render. One of url, html or markdown is required.

markdownstring

The Markdown to render. One of url, html or markdown is required.

response_type'by_format' | 'empty' | 'json'

What to return: by_format returns the result in the requested format, empty returns only the status or the error, and json returns a JSON object, which has data only for the options that produce it, like caching, storage or metadata.

attachment_namestring

The name of the file to download the result as. The extension is added from the format.

dark_modeboolean

Set to true to request the dark mode of the site and to false to request the light one, if the site supports them. Not set by default.

reduced_motionboolean

Emulates the prefers-reduced-motion: reduce preference. The site decides how to respond to it.

reduce_motionboolean

Actively reduces motion on the page before capturing it: animations, carousels and background videos.

media_type'screen' | 'print'

The media type to emulate: print renders the page as for printers, screen as for screens.

scriptsstring

JavaScript to inject into the page and execute before capturing.

scripts_wait_untilstring[]

The events to wait for after the injected scripts were executed. Use it when a script navigates to another page.

stylesstring

CSS to inject into the page.

hide_selectorsstring[]

Selectors of the elements to hide before capturing. All elements matching each selector are hidden with display: none.

hoverstring

A selector of the element to hover over before capturing.

error_on_hover_selector_not_foundboolean

Whether to return an error when the element to hover over is not found.

clickstring

A selector of the element to click before capturing.

error_on_click_selector_not_foundboolean

Whether to return an error when the element to click is not found.

include_shadow_domboolean

Includes the open and closed shadow DOM roots when the content of the page is extracted, for format=html or metadata_content=true.

bypass_cspboolean

Bypasses the Content Security Policy of the site. It may be needed for injected scripts to work.

viewport_device'blackberry_playbook' | 'blackberry_playbook_landscape' | 'blackberry_z30' | 'blackberry_z30_landscape' | 'galaxy_note_3' | 'galaxy_note_3_landscape' | 'galaxy_note_ii' | 'galaxy_note_ii_landscape' | 'galaxy_s_iii' | 'galaxy_s_iii_landscape' | 'galaxy_s5' | 'galaxy_s5_landscape' | 'galaxy_s8' | 'galaxy_s8_landscape' | 'galaxy_s9+' | 'galaxy_s9+_landscape' | 'galaxy_tab_s4' | 'galaxy_tab_s4_landscape' | 'ipad' | 'ipad_landscape' | 'ipad_gen_6' | 'ipad_gen_6_landscape' | 'ipad_gen_7' | 'ipad_gen_7_landscape' | 'ipad_mini' | 'ipad_mini_landscape' | 'ipad_pro' | 'ipad_pro_landscape' | 'ipad_pro_11' | 'ipad_pro_11_landscape' | 'iphone_4' | 'iphone_4_landscape' | 'iphone_5' | 'iphone_5_landscape' | 'iphone_6' | 'iphone_6_landscape' | 'iphone_6_plus' | 'iphone_6_plus_landscape' | 'iphone_7' | 'iphone_7_landscape' | 'iphone_7_plus' | 'iphone_7_plus_landscape' | 'iphone_8' | 'iphone_8_landscape' | 'iphone_8_plus' | 'iphone_8_plus_landscape' | 'iphone_se' | 'iphone_se_landscape' | 'iphone_x' | 'iphone_x_landscape' | 'iphone_xr' | 'iphone_xr_landscape' | 'iphone_11' | 'iphone_11_landscape' | 'iphone_11_pro' | 'iphone_11_pro_landscape' | 'iphone_11_pro_max' | 'iphone_11_pro_max_landscape' | 'iphone_12' | 'iphone_12_landscape' | 'iphone_12_pro' | 'iphone_12_pro_landscape' | 'iphone_12_pro_max' | 'iphone_12_pro_max_landscape' | 'iphone_12_mini' | 'iphone_12_mini_landscape' | 'iphone_13' | 'iphone_13_landscape' | 'iphone_13_pro' | 'iphone_13_pro_landscape' | 'iphone_13_pro_max' | 'iphone_13_pro_max_landscape' | 'iphone_13_mini' | 'iphone_13_mini_landscape' | 'iphone_14' | 'iphone_14_landscape' | 'iphone_14_plus' | 'iphone_14_plus_landscape' | 'iphone_14_pro' | 'iphone_14_pro_landscape' | 'iphone_14_pro_max' | 'iphone_14_pro_max_landscape' | 'iphone_15' | 'iphone_15_landscape' | 'iphone_15_plus' | 'iphone_15_plus_landscape' | 'iphone_15_pro' | 'iphone_15_pro_landscape' | 'iphone_15_pro_max' | 'iphone_15_pro_max_landscape' | 'iphone_16' | 'iphone_16_landscape' | 'iphone_16_plus' | 'iphone_16_plus_landscape' | 'jiophone_2' | 'jiophone_2_landscape' | 'kindle_fire_hdx' | 'kindle_fire_hdx_landscape' | 'lg_optimus_l70' | 'lg_optimus_l70_landscape' | 'microsoft_lumia_550' | 'microsoft_lumia_950' | 'microsoft_lumia_950_landscape' | 'nexus_10' | 'nexus_10_landscape' | 'nexus_4' | 'nexus_4_landscape' | 'nexus_5' | 'nexus_5_landscape' | 'nexus_5x' | 'nexus_5x_landscape' | 'nexus_6' | 'nexus_6_landscape' | 'nexus_6p' | 'nexus_6p_landscape' | 'nexus_7' | 'nexus_7_landscape' | 'nokia_lumia_520' | 'nokia_lumia_520_landscape' | 'nokia_n9' | 'nokia_n9_landscape' | 'pixel_2' | 'pixel_2_landscape' | 'pixel_2_xl' | 'pixel_2_xl_landscape' | 'pixel_3' | 'pixel_3_landscape' | 'pixel_4' | 'pixel_4_landscape' | 'pixel_4a_5g' | 'pixel_4a_5g_landscape' | 'pixel_5' | 'pixel_5_landscape' | 'moto_g4' | 'moto_g4_landscape'

A device to emulate instead of setting the viewport options one by one. It sets the viewport, the scale factor and the user agent. The list of devices is returned by the /devices method.

viewport_widthinteger

The width of the browser viewport in pixels. Overrides the value set by viewport_device.

viewport_heightinteger

The height of the browser viewport in pixels. Overrides the value set by viewport_device.

device_scale_factornumber

The device scale factor (device pixel ratio), from 1 to 5, fractions are allowed. Overrides the value set by viewport_device.

viewport_mobileboolean

Whether the meta viewport tag is taken into account. Overrides the value set by viewport_device.

viewport_has_touchboolean

Whether the viewport supports touch events. Overrides the value set by viewport_device.

viewport_landscapeboolean

Whether the viewport is in landscape mode. Overrides the value set by viewport_device.

geolocation_latitudenumber

The latitude of the geolocation to emulate. Latitude and longitude must be set together.

geolocation_longitudenumber

The longitude of the geolocation to emulate. Latitude and longitude must be set together.

geolocation_accuracyinteger

The accuracy of the emulated geolocation in meters.

ip_country_code'us' | 'gb' | 'de' | 'it' | 'fr' | 'cn' | 'ca' | 'es' | 'jp' | 'kr' | 'in' | 'au' | 'br' | 'mx' | 'nz' | 'pe' | 'is' | 'ie'

The country to render the site from, through the proxies provided by ScreenshotOne. It can't be used together with proxy.

block_cookie_bannersboolean

Blocks cookie banners, GDPR overlays and other privacy notices.

block_banners_by_heuristicsboolean

Blocks banners with a different set of techniques and heuristics. Try it when block_cookie_banners doesn't help; it may change how the page looks.

block_chatsboolean

Blocks chat widgets like Intercom, Crisp, Drift, Tawk and others.

block_adsboolean

Blocks ads.

block_trackersboolean

Blocks trackers, so the rendering is not counted as a visit by analytics.

block_requestsstring[]

Blocks the requests of the page that match a URL, a domain or a pattern like *.example.com/*. Up to 100 patterns.

block_resourcesstring[]

Blocks loading the resources of the page by type.

cacheboolean

Caches the result. A cached result is reused for the requests with the same options.

cache_ttlinteger

How long a cached result is reused, in seconds: from 14400 (4 hours, the default) to 2592000 (1 month). Requires cache=true.

cache_keystring

An alphanumeric key to keep different cached versions of the result for the same options. Requires cache=true.

user_agentstring

The user agent of the browser. Changing it may break the stealth mode; it overrides the user agent set by viewport_device.

authorizationstring

The value of the Authorization header to send to the site, for pages protected by basic authentication or a token.

headersstring[]

Extra HTTP headers to send to the site, each in the format Header-Name:Header-Value.

cookiesstring[]

Cookies to set for the site, each in the format name=value; Domain=example.com; Secure; HttpOnly.

proxystring uri

The URL of your own HTTP proxy to render the site through, like http://user:password@host:port. It can't be used together with ip_country_code.

proxy_bypass_hostsstring[]

Hostname patterns of the requests to load directly and not through the proxy. Requires proxy.

time_zone'America/Belize' | 'America/Cayman' | 'America/Chicago' | 'America/Costa_Rica' | 'America/Denver' | 'America/Edmonton' | 'America/El_Salvador' | 'America/Guatemala' | 'America/Guayaquil' | 'America/Hermosillo' | 'America/Jamaica' | 'America/Los_Angeles' | 'America/Mexico_City' | 'America/Nassau' | 'America/New_York' | 'America/Panama' | 'America/Port-au-Prince' | 'America/Santiago' | 'America/Tegucigalpa' | 'America/Tijuana' | 'America/Toronto' | 'America/Vancouver' | 'America/Winnipeg' | 'Asia/Kuala_Lumpur' | 'Asia/Shanghai' | 'Asia/Tashkent' | 'Europe/Berlin' | 'Europe/Kiev' | 'Europe/Lisbon' | 'Europe/London' | 'Europe/Madrid' | 'Pacific/Auckland' | 'Pacific/Majuro'

The time zone of the browser.

delayinteger

The time in seconds to wait before capturing, after the page is loaded. Up to 30, or up to 300 when timeout is greater than 300.

timeoutinteger

The time in seconds after which the request is aborted. The default is 60 and the maximum is 90; both are 600 for async requests.

navigation_timeoutinteger

The time in seconds after which the request is aborted when the site doesn't respond.

wait_untilstring[]

The events to wait for before capturing: load, domcontentloaded, networkidle0 (no network connections for 500 ms) or networkidle2 (no more than two).

wait_for_selectorstring

A selector of the element to wait for before capturing. The element must appear in the DOM, but may be invisible.

wait_for_selector_algorithm'at_least_one' | 'at_least_by_count'

With several selectors in wait_for_selector: at_least_one waits until at least one of them is matched, at_least_by_count waits until as many elements are matched as there are selectors, not necessarily one for each selector.

fail_if_content_containsstring[]

Fails the request when the content of the page contains any of the given strings, case-insensitive.

fail_if_content_missingstring[]

Fails the request when the content of the page misses any of the given strings, case-insensitive.

fail_if_request_failedstring[]

Fails the request when a request of the page matching one of the given patterns fails or returns an error status. Up to 100 patterns.

ignore_host_errorsboolean

Renders the page even when the site responds with a status outside of the 200-299 range. Without it, the host_returned_error error is returned.

request_gpu_renderingboolean

Asks to render with hardware (GPU) acceleration. It is a hint, available on the top-tier paid plans: rendering without GPU is used when the GPU servers are unavailable.

fail_if_gpu_rendering_failsboolean

Fails the request when GPU rendering fails, instead of falling back to rendering without GPU.

asyncboolean

Executes the request asynchronously: the API returns an empty response immediately. Usually combined with webhook_url or the storage options. Caching is not available for async requests.

webhook_urlstring uri

A public HTTPS URL to send the result of the request to.

webhook_signboolean

Whether to sign the body of the webhook request.

webhook_errorsboolean

Sends the details of a failed request to the webhook, too.

external_identifierstring

An alphanumeric identifier of your own that is sent back in the x-screenshotone-external-identifier header of the webhook request.

storeboolean

Uploads the result to the configured S3-compatible storage.

storage_bucketstring

The bucket to upload to. Overrides the one configured in the dashboard.

storage_pathstring

The key of the file in the bucket, without an extension: it is added from the format. Required when store=true.

storage_endpointstring uri

The endpoint of an S3-compatible storage, like Cloudflare R2. Leave it out for Amazon S3.

storage_access_key_idstring

The access key ID of the storage. Overrides the one configured in the dashboard.

storage_secret_access_keystring

The secret access key of the storage. Overrides the one configured in the dashboard.

storage_acl'public-read' | ''

The ACL of the uploaded file: public-read, or not set.

storage_class'standard' | 'reduced_redundancy' | 'standard_ia' | 'onezone_ia' | 'intelligent_tiering' | 'glacier' | 'deep_archive' | 'outposts' | 'glacier_ir'

The storage class of the uploaded file.

storage_return_locationboolean

Returns the location of the uploaded file: in the X-ScreenshotOne-Store-Location header, or in the JSON response.

metadata_fontsboolean

Returns the fonts the page uses.

metadata_contentboolean

Returns the content of the page in addition to the result: a temporary URL of the stored content and when it expires, in the X-ScreenshotOne-Content-URL and X-ScreenshotOne-Content-Expires headers, or in the JSON response.

metadata_content_format'html' | 'markdown'

The format of the content returned by metadata_content: html or markdown.

metadata_page_titleboolean

Returns the title of the page: in the x-screenshotone-page-title header, or in the JSON response.

metadata_open_graphboolean

Returns the Open Graph metadata of the page: in the x-screenshotone-open-graph header, or in the JSON response.

metadata_http_response_status_codeboolean

Returns the HTTP status code the site responded with. Only for requests with url.

metadata_http_response_headersboolean

Returns the HTTP headers the site responded with. Only for requests with url.

metadata_iconboolean

Returns the icon (favicon) of the site.

format'mp4' | 'avi' | 'mov' | 'webm' | 'gif'

The format of the animation.

durationnumber

The duration of the animation in seconds. With scroll_complete=true, the recording stops earlier when the scrolling is completed.

omit_backgroundboolean

Renders a transparent background when the page doesn't define one. Only for format=mov.

widthinteger

The width of the video in pixels. Set together with height; by default, the width of the viewport. Not used when aspect_ratio is set.

heightinteger

The height of the video in pixels. Set together with width; by default, the height of the viewport. Not used when aspect_ratio is set.

aspect_ratio'4:3' | '16:9'

The aspect ratio to fit the video of the viewport into.

clip_xinteger

The left coordinate (x) of the area of the video to clip. Only for format=gif.

clip_yinteger

The top coordinate (y) of the area of the video to clip. Only for format=gif.

clip_widthinteger

The width of the area of the video to clip. Only for format=gif.

clip_heightinteger

The height of the area of the video to clip. Only for format=gif.

scenario'' | 'default' | 'scroll'

The scenario of the animation: default records the page as it is, scroll records scrolling the page.

scroll_durationnumber

The duration of one scroll in milliseconds. It is not the duration of the animation.

scroll_delaynumber

The delay between the scrolls in milliseconds.

scroll_bynumber

How many pixels to scroll by at a time.

scroll_easing'linear' | 'ease_in_quad' | 'ease_out_quad' | 'ease_in_out_quad' | 'ease_in_cubic' | 'ease_out_cubic' | 'ease_in_out_cubic' | 'ease_in_quart' | 'ease_out_quart' | 'ease_in_out_quart' | 'ease_in_quint' | 'ease_out_quint' | 'ease_in_out_quint'

The easing effect of the scrolling.

scroll_start_immediatelyboolean

Whether to start scrolling immediately or to wait for scroll_delay first.

scroll_start_delaynumber

The time to wait before the scrolling starts, in milliseconds.

scroll_completeboolean

Stops the recording when the scrolling is completed, even when it is earlier than duration.

scroll_backboolean

Whether to scroll back to the top after reaching the bottom of the page.

scroll_back_algorithm'once' | 'repeat'

How to scroll back: once scrolls back in one move, repeat repeats the same steps the page was scrolled down with.

scroll_back_after_durationinteger

Scrolls back after the given time in milliseconds. Can't be used with scroll_stop_after_duration.

scroll_stop_after_durationinteger

Stops scrolling after the given time in milliseconds. Requires scroll_back=false.

scroll_to_end_afterinteger

Scrolls to the end of the page in one scroll after the given time in milliseconds. Only for scenario=scroll.

scroll_till_selectorstring

A selector of the element to scroll to; the scrolling stops when the element is visible.

scroll_till_selector_adjust_topinteger

How many pixels to shift the element given in scroll_till_selector from the top of the viewport.

scroll_try_navigateboolean

Navigates to another page while scrolling and records the opened page.

scroll_navigate_afterinteger

The time in milliseconds after which to navigate. By default, half of the duration.

scroll_navigate_to_urlstring uri

The URL to navigate to while scrolling.

scroll_navigate_link_hintsstring[]

When scroll_navigate_to_url is not set, the keywords to choose an internal link to navigate to by its text.

Response

A successful recording of a website, HTML, or Markdown.

Changes