Skip to main content

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:

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
}
]
}

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

string Default: ""

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

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

string Default: ""

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

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"
}
]
}

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"
}
]
}

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": "/"
}
]
}

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

number Default: <null>

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

Forbids JavaScript from accessing the cookie.

boolean Default: <null>

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

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
}
]
}

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 }