API Documentation

Introduction

The URL2IMG API is a JSON REST API that provides lightning-fast, high-quality screenshots of websites or URLs.

API requests are made using a friendly URL structure and successful results are returned as images or errors in JSON format, providing a simple integration and full compatibility with any application, programming language or framework.

This API documentation explains all the parameters and features with API call examples that can be tested in your browser.

                        
                        https://url2img.com/api/v1/

Authentication

After signing up you will receive an API access key (shown in your dashboard) used to access any of the API endpoints.

To authenticate with the API you must provide your API access key in the access_key parameter of the API endpoint URL:

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com

Errors

If your request fails the API will return a JSON response containing a 3-digit error code along with an internal error type and a plain text "info" parameter with suggestions on how to correct the error.

Below is an example error caused by providing an invalid API Access Key.

{
  "success": false,
  "error": {
    "code": 102,
    "type": "invalid_access_key",
    "info": "You supplied an invalid Access Key."
  }
}

API error codes:

Code	Type	Description
101	missing_access_key	You did not supply an Access Key.
102	invalid_access_key	You supplied an invalid Access Key.
104	usage_limit_reached	You have reached your subscription plan's monthly API request allowance.
301	missing_property	A required parameter has not been supplied.
311	invalid_url	You have supplied an invalid URL for the "url" parameter.
404	404_not_found	The requested API resource does not exist.
429	too_many_requests	You have exceeded the maximum allowed rate limitation as defined by your subscription plan. Please refer to the Rate Limits section of the API Documentation.
500	server_error	Something went wrong - Internal server error.

Please Note: This is not a complete list of errors. If you come receive an error message you are not sure about please contact our support.

Rate Limits

Requests to the API are rate limited based on your current subscription plan:

Subscription Plan	API Rate Limit
Free	1 Simultaneous Request
Startup	5 Simultaneous Requests
Growth	10 Simultaneous Requests
Enterprise	20 Simultaneous Requests

Capture Overview

The capture endpoint allows you to take a screenshot of any website or URL and have it returned as an image.

                            
                            https://url2img.com/api/v1/capture

Required Parameters:

Parameter	Description
access_key	Your API Access Key (Found in your dashboard).
url	The full URL (including protocol) of the website you want to request a screenshot from, e.g. https://www.yahoo.com

Important!

If the url parameter contains any special characters such as & or ? then it must be url encoded.

For example, if you wish to capture the URL "https://www.example.com?q=hello&page=2" you would need to URL encode this to become https%3A%2F%2Fwww.example.com%3Fq%3Dhello%26page%3D2

If you are still not 100% sure you can find more information about URL encoding here https://www.w3schools.com/tags/ref_urlencode.ASP

Optional Parameters:

Parameter	Description	Default
fullpage	An integer boolean value. If set to 1 the resulting screenshot will be the full height of the website or URL. If set to 0 then the result will be the height of the viewport.	0
width	The required integer width in pixels of the resulting screenshot. This will scale the image and allows you to generate a thumbnail image rather than a full-size screenshot.	100% (full width of content within viewport)
viewport	The required viewport dimensions in pixels. This allows you to use different display sizes and should be in the format WIDTH x HEIGHT.	1440x900
format	The image format of the resulting screenshot. This can either be "png" or "jpg"	png
css_url	A URL containing a .css file that will be included when the URL is loaded. This can be used to alter fonts, colours or add watermarks etc to the resulting screenshot image.
delay	An integer value in seconds used to control the time when the image is captured. This is useful when sites may be slow to load.
ttl	An integer value in seconds used to control when a new screenshot should be generated if one is cached already.	2592000 (30 days)
force	An integer boolean value. If set to 1 then a new screenshot will be generated. If set to 0 then we will use a cached image if one exists below the ttl value.	0
user_agent	A string used to set a custom User-Agent HTTP header when requesting the URL. This allows you to emulate different devices or platforms.	The latest desktop chrome browser
accept_lang	A string used to set a custom Accept-Language HTTP header when requesting the URL. This allows you to emulate different languages.	en-US,en;q=0.5
auth_user	A string used to specify the HTTP authentication username when accessing a password protected URL
auth_pass	A string used to specify the HTTP authentication password when accessing a password protected URL
no_images	An integer boolean value. If set to 1 then images will be disabled in the generated screenshot.	0
no_javascript	An integer boolean value. If set to 1 then javascript will be disabled when rendering the HTML to generate the screenshot.	0
no_dialogs	An integer boolean value. If set to 1 then popups will be closed when rendering the HTML to generate the screenshot.	0
use_print_media	An integer boolean value. If set to 1 then the @media print CSS will be enabled when rendering the HTML to generate the screenshot.	0
greyscale	An integer boolean value. If set to 1 then the screenshot will be generated in greyscale with no colours.	0

Full Page

The fullpage parameter is an integer boolean that can have the values of 0 or 1. This allows you to request the full height of the website or URL by setting it to the value 1.

By default, this is set to the value 0 so the captured image will only contain whatever parts of the website fit into the viewport.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&fullpage=1

Width

The width parameter is an integer value and allows you to request the screenshot image to be scaled to a specific width in pixels.

This will scale the height of the image proportionally to this width.

By default, this is not set so the captured image will be the full width of the website or the part which fits within the viewport.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&width=600

Viewport

The viewport parameter is a string composed of a width and a height as integer pixel values separated by an "x" which allows you to request the website or URL with specific screen size.

Details of common device viewports can be found at https://screensiz.es/.

This can be set to a maximum of 5000x5000 and a minimum of 1x1.

By default, this is set to the value 1440x900 so the captured image will only contain whatever parts of the website fit into the viewport.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&viewport=600x400

Format

The format parameter is a string that sets the image format that you wish to receive the screenshot image as.

The value can be set to png or jpg.

By default, this is set to the value "png".

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&format=jpg

CSS URL

The css_url parameter is a string that allows you to pass the URL of a .css file which will be loaded before the screenshot is taken.

This allows you to customise the page or add watermarks etc.

By default, this is not set.

Important!

If the css_url parameter contains any special characters such as & or ? then it must be url encoded.

For example, if you wish to capture the URL "https://www.example.com/css.css?v=1" you would need to URL encode this to become https%3A%2F%2Fwww.example.com%2Fcss.css%3Fv%3D1

If you are still not 100% sure you can find more information about URL encoding here https://www.w3schools.com/tags/ref_urlencode.ASP

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&&css_url=https://url2img.com/css/css_url_example.css

Delay

The delay parameter is an integer value and allows you to request the screenshot image to be delayed for a specific number of seconds.

This can be set to a maximum of 60.

By default, this is not set so the screenshot will be taken after the site has fully loaded.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&delay=30

TTL

The ttl (Time To Live) parameter is an integer value and allows you to request the screenshot image to be cached for a specific number of seconds.

This can be set to a maximum of 2592000 (30 days).

By default, this is set to 2592000 so the screenshot will be cached for 30 days.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&ttl=86400

Force

The force parameter is a boolean integer value and allows you to request the screenshot to be retaken each time so no cache is used.

This can be set to 1 or 0.

By default, this is set to 0 so the ttl value will be used.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&force=1

User Agent

The user_agent parameter is a string value that allows you to specify a custom User-Agent HTTP header to be sent with the URL request enabling you to emulate different devices.

A list of common User-Agent strings can be found at https://developers.whatismybrowser.com/

By default, this is set to the most recent Google Chrome desktop browser.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&user_agent=Mozilla/5.0 (Linux; U; Android 2.2) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0 Mobile Safari/533.1

Accept-Language

The accept_lang parameter is a string value that allows you to specify a custom Accept-Language HTTP header to be sent with the URL request enabling you to emulate different browser languages.

A list of common language strings can be found at http://4umi.com/web/html/languagecodes.php

By default this is set to "en-US,en;q=0.5" (US English).

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&accept_lang=fr-FR

Auth User

The auth_user parameter is a string that allows you to provide the username to be used when accessing a password protected URL or website.

By default, this is not set.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&auth_user=steve

Auth Pass

The auth_pass parameter is a string that allows you to provide the password to be used when accessing a password protected URL or website.

By default, this is not set.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&auth_pass=pass123

No Images

The no_images parameter is a boolean integer value and allows you to request the resulting screenshot to be generated without any images in the content.

If set to 1 then images will be excluded.

This can be set to 1 or 0.

By default, this is set to 0 so images will be shown in the Image.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&no_images=1

No JavaScript

The no_javascript parameter is a boolean integer value and allows you to request the resulting screenshot to be generated without any JavaScript being run.

If set to 1 then JavaScript will be disabled.

This can be set to 1 or 0.

By default, this is set to 0 so JavaScript will be active.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&no_javascript=1

No Dialogs

The no_dialogs parameter is a boolean integer value and closes popups disallowing the screenshot to be taken.

If set to 1 then dialogs will be closed.

This can be set to 1 or 0.

By default, this is set to 0 so dialogs will be shown in the screenshot.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&no_dialogs=1

Use Print Media

The use_print_media parameter is a boolean integer value and allows you to request the resulting screenshot document to be generated using the "print" media type.

If set to 1 then the "print" media type will be used and any CSS @media print declarations will become active.

This can be set to 1 or 0.

By default, this is set to 0 so the "screen" media type will be used.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&use_print_media=1

Greyscale

The greyscale parameter is a boolean integer value and allows you to request the resulting screenshot to be generated in greyscale.

If set to 1 then greyscale will be used and all colours removed.

This can be set to 1 or 0.

By default, this is set to 0 so the screenshot will show all colours.

                        
                       https://url2img.com/api/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://url2img.com&greyscale=1

Access & Specification

Capture API

API Documentation

Introduction

Authentication

Errors

API error codes:

Rate Limits

Capture Overview

Required Parameters:

Important!

Optional Parameters:

Full Page

Width

Viewport

Format

CSS URL

Important!

Delay

TTL

Force

User Agent

Accept-Language

Auth User

Auth Pass

No Images

No JavaScript

No Dialogs

Use Print Media

Greyscale