Html to Image

Convert any HTML to an Image using any valid HTML, CSS, Javascript, SASS, etc. As long as the base64 encoded JSON payload is below 10MB in size, we will accept it and convert it.

Endpoints

POST /html/image

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

Html Parameters
Base Parameters

POST /html/image

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

JSON Payload
{ "html": "PGh0bWw+PGJvZHk+PGgxPkhlbGxvIHdvcmxkITwvaDE+PC9ib2R5PjwvaHRtbD4=" }

Examples

Viewport Example
{
  "html": "PGh0bWw+PGJvZHk+PGgxPkhlbGxvIHdvcmxkITwvaDE+PC9ib2R5PjwvaHRtbD4=",
  "viewPort": {
    "width": 800,
    "height": 400
  }
}

cURL Example
curl --request POST \
  --url https://api.cloudlayer.io/v2/html/image \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --data '{
    "html": "PGh0bWw+PGJvZHk+PGgxPkhlbGxvIHdvcmxkITwvaDE+PC9ib2R5PjwvaHRtbD4="
}' \
--output "response.json"

Wget Example
wget --method POST \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --body-data '{"html": "PGh0bWw+PGJvZHk+PGgxPkhlbGxvIHdvcmxkITwvaDE+PC9ib2R5PjwvaHRtbD4="}' \
  - https://api.cloudlayer.io/v2/html/image \
  -O "response.json"

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.

info

For more examples, checkout the Examples section.

Html Parameters

Parameters that exist on HTML services.

`html`

The base64 encoded HTML string of your HTML. Must be a base64 encoded string.

Required

string Default: ""

Raw HTML
<html>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>

Base64 Encoded
{ "html": "PGh0bWw+PGJvZHk+PGgxPkhlbGxvIHdvcmxkITwvaDE+PC9ib2R5PjwvaHRtbD4=" }

tip

If you are using VSCode you can download the vscode-base64 extension to help you encode/decode your HTML while you develop.

info

For more examples and more complex scenarios, check out the Examples section.

Base Parameters

Parameters that exist on all services.

`autoScroll`

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

boolean Default: false

{ "autoScroll": true }

`delay`

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

number Default: 0ms

{ "delay": 1000 }

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

`generatePreview`

Generates an image preview (thumbnail) of the image or first page of the PDF document. Storage must be enabled.

All parameters are optional, if you pass in true to generatePreview instead of options it will use defaults.

{
  "width": 600,
  "height": 776,
  "type": "webp",
  "quality": 75
}

`height`

Height of the image to generate for the preview

number Optional - Either width or height must be provided. If maintainAspectRatio is being used, you may specify either one or the other.

 "height": 600

`width`

Width of the image to generate for the preview

number Optional - Either width or height must be provided. If maintainAspectRatio is being used, you may specify either one or the other.

{
  "width": 300
}

`type`

Optional

string Default: "webp"

Type of image to generate for the preview.

Must be one of the following:

png
jpg
webp

{
  "type": "webp"
}

`maintainAspectRatio`

boolean Default: true

Either true or false to indicate if the image generated should maintain aspect ratio based on width/height.

Can result in a blurry and skewed image if the aspect ratio is not maintained

{
  "maintainAspectRatio": true
}

`quality`

string Default: 80

Optional

Specifies the quality of the generated preview.

Must be a number between 0-100.

{
  "quality": 80
}

info

Generating a preview can add significant processing time depending on the quality and size of the preview image and PDF document. It's important to balance quality and rendering time.

`height / width`

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

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

`landscape`

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

boolean `Default: false

{ "landscape": true }

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

`projectId`

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

string Default: ""

{ "projectId": "N77VCoAVTHHwgmUfCYlD" }

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

`scale`

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

number Default: 0

{ "scale": 0.5 }

`timeout`

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

number Default: 30000ms

{ "timeout": 30000 }

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

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

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

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

Image Parameters

Parameters that exist on all image service endpoints.

`imageType`

string Default: "png"

Type of image to generate for the preview.

Must be one of the following:

png
jpg
webp

{
  "imageType": "webp"
}

`transparent`

boolean Default: false

Either true or false to indicate if the background should be transparent.

Note: Has no effect if the image type does not support transparency.

{
  "transparent": true
}

`trim`

boolean Default: false

Either true or false to indicate if whitespace around the image should be trimmed.

{
  "trim": true
}

;

Endpoints​

POST /html/image​

Examples​

Html Parameters​

html​

Base Parameters​

autoScroll​

delay​

filename​

generatePreview​

height​

width​

type​

maintainAspectRatio​

quality​

height / width​

height​

width​

inline​

landscape​

preferCSSPageSize​

projectId​

height​

deviceScaleFactor​

isMobile​

hasTouch​

isLandscape​

scale​

timeout​

timeZone​

viewPort​

width​

waitForSelector​

selector​

options​

visible​

hidden​

timeout​

waitUntil​

Accepted Values​

Image Parameters​

imageType​

transparent​

trim​

Endpoints

POST /html/image

Examples

Html Parameters

`html`

Base Parameters

`autoScroll`

`delay`

`filename`

`generatePreview`

`height`

`width`

`type`

`maintainAspectRatio`

`quality`

`height / width`

`height`

`width`

`inline`

`landscape`

`preferCSSPageSize`

`projectId`

`height`

`deviceScaleFactor`

`isMobile`

`hasTouch`

`isLandscape`

`scale`

`timeout`

`timeZone`

`viewPort`

`width`

`waitForSelector`

`selector`

`options`

`visible`

`hidden`

`timeout`

`waitUntil`

Accepted Values

Image Parameters

`imageType`

`transparent`

`trim`