Url to Image

Convert any URL to an Image using a publicly accessible webpage URL or one behind basic authentication or cookie authentication using our authentication mechanisms.

Endpoints

GET /url/image

Supports simple requests with only two parameter options.

url (required)
timeout (optional)

GET /url/image

https://api.cloudlayer.io/v2/url/image?url={url}&timeout={timeout}

POST /url/image

Supports all parameters being passed into request as JSON. The following parameter types are supported:

Url Parameters
Base Parameters

tip

Make sure your Content-Type gets set to application/json, and that you have placed your X-API-Key header with your API Key from your account.

POST /url/image

https://api.cloudlayer.io/v2/url/image

JSON Payload
{
  "url": "https://google.com"
}

Examples

Viewport Example
{
  "url": "https://google.com",
  "viewPort": {
    "width": 800,
    "height": 400
  }
}

cURL Example
curl --request POST \
  --url https://api.cloudlayer.io/v2/url/image \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --data '{
    "url": "https://google.com"
}' \
--output "google.png"

Wget Example
wget --method POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --body-data '{"url": "https://google.com"}' \
  - https://api.cloudlayer.io/v2/url/image \
  -O "google.png"

info

For more examples, checkout the Examples section.

Url Parameters

Parameters that exist on URL services.

`url`

Source URL to use for generating the content.

Required

string Default: ""

{ "url": "http://google.com" }

`authentication`

Provide credentials for HTTP authentication (Basic Auth).

{
  "authentication": {
    "username": "bob",
    "password": "abc123"
  }
}

`username`

The username for authenticating. Username and Password are both required.

Required

string Default: ""

{
  "authentication": {
    "username": "bob",
    "password": "..."
  }
}

`password`

The password for authenticating. Username and Password are both required.

Required

string Default: ""

{
  "authentication": {
    "username": "...",
    "password": "abc123"
  }
}

`cookies`

Sets up one to many cookies for the page prior to navigation.

{
  "cookies": [
    {
      "name": "cookie_notice_accept",
      "value": "1",
      "domain": "www.example.com",
      "path": "/",
      "expires": 1668752280
    },
    {
      "name": "_session_id",
      "value": "ad9a8u90f0df7d87fdas9fa892342",
      "domain": "www.example.com",
      "path": "/",
      "expiration": 1668752280,
      "httpOnly": true
    }
  ]
}

`name`

The name of the cookie to set. Name and value are both required. Required

string Default: ""

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "..."
    }
  ]
}

`value`

The name of the cookie to set. Name and value are both required. Required

string Default: ""

{
  "cookies": [
    {
      "name": "...",
      "value": "SomeCookieValue"
    }
  ]
}

`url`

The url to use for the cookie. This is usually left empty.

string Default: ""

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "url": "https://www.example.com"
    }
  ]
}

`domain`

Defines the host to which the cookie will be sent. If omitted, this attribute defaults to the host of the current document URL, not including subdomains.

string Default: ""

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "domain": "www.example.com"
    }
  ]
}

`path`

Indicates the path that must exist in the requested URL for the browser to send the Cookie header.

string Default: ""

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "path": "/"
    }
  ]
}

`expires`

Indicates the maximum lifetime of the cookie as an Unix time integer.

number Default: <null>

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "expires": 1668752280
    }
  ]
}

`httpOnly`

Forbids JavaScript from accessing the cookie.

boolean Default: <null>

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "httpOnly": true
    }
  ]
}

`secure`

Indicates that the cookie is sent to the server only when a request is made with the https: scheme.

boolean Default: <null>

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "secure": true
    }
  ]
}

`sameSite`

Controls whether or not a cookie is sent with cross-origin requests.

string<"Strict|Lax"> Default: <null>

Values

Strict
Lax

{
  "cookies": [
    {
      "name": "myCookie",
      "value": "some_data",
      "sameSite": "Strict"
    }
  ]
}

Base Parameters

Parameters that exist on all services.

`waitUntil`

When to consider the navigation has been completed and begin the conversion.

string Default: "networkidle2"

Accepted Values

load - consider navigation to be finished when the load event is fired.
domcontentloaded - consider navigation to be finsihed when the DOMContentLoaded event is fired.
networkidle0 - consider navigation to be finished when there are no more than 0 network connections for at least 500 ms.
networkidle2 - consider navigation to be finished when there are no more than 2 network connections for at least `500' ms.

{ "waitUntil": "load" }

`timeout`

Amount of time that Chrome is allowed to run. If exceeded, your job will terminate.

number Default: 30000ms

{ "timeout": 30000 }

`delay`

The amount of time in milliseconds to wait for the page to complete rendering before conversion.

number Default: 0ms

{ "delay": 1000 }

`autoScroll`

Will auto-scroll the page down to the very end. Helpful in forcing lazy-loaded content to load.

boolean Default: false

{ "autoScroll": true }

`filename`

If used with the inline: false, will set the Content-Disposition filename so that the downloaded file will assign to this value in the user's browser. For inline: true, it has no effect.

string Default: ""

{ "filename": "filename.ext" }

`inline`

If set to true, the Content-Disposition gets set to inline. If set to false, it gets set to attachment. See filename property if you want to set the filename value for the attachment.

boolean Default: false

{ "inline": true }

`projectId`

The project's id you would like the job and any assets the job generates to be a member.

string _Default: ""

{ "projectId": "N77VCoAVTHHwgmUfCYlD" }

`viewPort`

Set the Viewport of the page before navigation.

{
  "viewPort": {
    "width": 1024,
    "height": 768,
    "deviceScaleFactor": 2
  }
}

`width`

Page width in pixels only. Required

number Default: <null>

{
  "viewPort": {
    "width": 1024
  }
}

`height`

Page height in pixels only. Required

number Default: <null>

{
  "viewPort": {
    "height": 768
  }
}

`deviceScaleFactor`

Specify device scale factor (DPR). Height and Width are always required.

number Default: 1

{
  "viewPort": {
    "width": 640,
    "height": 480,
    "deviceScaleFactor": 1
  }
}

`isMobile`

Whether the meta viewport tag is taken into account. Height and Width are always required.

boolean Default: false

{
  "viewPort": {
    "width": 640,
    "height": 480,
    "isMobile": true
  }
}

`hasTouch`

Specifies if viewport supports touch events. Height and Width are always required.

boolean Default: false

{
  "viewPort": {
    "width": 640,
    "height": 480,
    "hasTouch": true
  }
}

`isLandscape`

Specifies if viewport is in landscape mode. Height and Width are always required.

boolean Default: false

{
  "viewPort": {
    "width": 640,
    "height": 480,
    "isLandscape": true
  }
}

`timeZone`

Changes the timezone of the page. See ICU's metaZones.txt for a list of supported timezone IDs.

string Default: <null>

{ "timeZone": "Europe/Rome" }

`waitForSelector`

Allows for more complex wait behavior to control when the Chrome rendering engine decides when a page has finished before the conversion.

`selector`

The selector of an element to wait for before performing the conversion.

string Default: <null>

{
  "waitForSelector": {
    "selector": "img"
  }
}

`options`

The selector of an element to wait for before performing the conversion.

`visible`

Wait for the selector element to be present in the DOM and to be visible, i.e. to not have display:none or visibility:hidden CSS properties. Not to be combined with the hidden property.

boolean Default: false

{
  "waitForSelector": {
    "selector": "img",
    "options": {
      "visible": true
    }
  }
}

`hidden`

Wait for the selector element to be present in the DOM and to be hidden, i.e. to have display: none or visibility: hidden CSS properties. Not to be combined with the visible property.

boolean Default: false

{
  "waitForSelector": {
    "selector": "img",
    "options": {
      "hidden": true
    }
  }
}

`timeout`

Maximum amount of time to wait in milliseconds for the selector to meet the visible or hidden criteria.

number Default: 30000

visible
{
  "waitForSelector": {
    "selector": "img",
    "options": {
      "visible": true,
      "timeout": 30000
    }
  }
}

hidden
{
  "waitForSelector": {
    "selector": "img",
    "options": {
      "hidden": true,
      "timeout": 30000
    }
  }
}

`preferCSSPageSize`

Give any CSS @page size declared in the page priority over what is declared in width and height or format options.

boolean Default: false

{ "preferCSSPageSize": true }

`scale`

Scale of the webpage rendering. Must be between 0.1 and 2.

number Default: 0

{ "scale": 0.5 }

`height`

Paper height. Must be supported type of units or number.

string|number Default: <null>

{ "height": 100 }

{ "height": "1.25in" }

`width`

Paper width. Must be supported type of units or number.

string|number Default: <null>

{ "width": 100 }

{ "width": "1.25in" }

`landscape`

Paper orientation, false sets it to portrait and true to landscape.

boolean `Default: false

{ "landscape": true }

Endpoints​

GET /url/image​

POST /url/image​

tip

Examples​

info

Url Parameters​

url​

authentication​

username​

password​

cookies​

name​

value​

url​

domain​

path​

expires​

httpOnly​

secure​

sameSite​

Base Parameters​

waitUntil​

Accepted Values​

timeout​

delay​

autoScroll​

filename​

inline​

projectId​

viewPort​

width​

height​

deviceScaleFactor​

isMobile​

hasTouch​

isLandscape​

timeZone​

waitForSelector​

selector​

options​

visible​

hidden​

timeout​

preferCSSPageSize​

scale​

height​

width​

landscape​

Endpoints

GET /url/image

POST /url/image

Examples

Url Parameters

`url`

`authentication`

`username`

`password`

`cookies`

`name`

`value`

`url`

`domain`

`path`

`expires`

`httpOnly`

`secure`

`sameSite`

Base Parameters

`waitUntil`

Accepted Values

`timeout`

`delay`

`autoScroll`

`filename`

`inline`

`projectId`

`viewPort`

`width`

`height`

`deviceScaleFactor`

`isMobile`

`hasTouch`

`isLandscape`

`timeZone`

`waitForSelector`

`selector`

`options`

`visible`

`hidden`

`timeout`

`preferCSSPageSize`

`scale`

`height`

`width`

`landscape`