HTML to Image

Generate an image (PNG, JPG, or WebP) from raw HTML content. The HTML is sent as a base64-encoded string in the request body.

Endpoint

POST /v1/html/image

All requests are processed synchronously. The response body is the raw image file.

POST /v2/html/image

Requests default to asynchronous processing (async: true, storage: true). Add "async": false to receive the raw image directly. See Sync vs. Async for details.

Quick Start

cURL

HTML_BASE64=$(echo '<html><body style="padding:40px;font-family:Arial"><h1 style="color:#2563eb">Hello World</h1><p>Generated by cloudlayer.io</p></body></html>' | base64)

curl -X POST "https://api.cloudlayer.io/v1/html/image" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d "{\"html\": \"$HTML_BASE64\"}" \
  --output result.png

JavaScript (fetch)

const html = `<html>
  <body style="padding: 40px; font-family: Arial;">
    <h1 style="color: #2563eb;">Hello World</h1>
    <p>Generated by cloudlayer.io</p>
  </body>
</html>`;

const response = await fetch("https://api.cloudlayer.io/v1/html/image", {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    html: btoa(html),
  }),
});

const image = await response.arrayBuffer();

Python (requests)

import base64
import requests

html = """<html>
  <body style="padding: 40px; font-family: Arial;">
    <h1 style="color: #2563eb;">Hello World</h1>
    <p>Generated by cloudlayer.io</p>
  </body>
</html>"""

response = requests.post(
    "https://api.cloudlayer.io/v1/html/image",
    headers={
        "X-API-Key": "your-api-key-here",
        "Content-Type": "application/json",
    },
    json={
        "html": base64.b64encode(html.encode()).decode(),
    },
)

with open("result.png", "wb") as f:
    f.write(response.content)

cURL

HTML_BASE64=$(echo '<html><body style="padding:40px;font-family:Arial"><h1 style="color:#2563eb">Hello World</h1><p>Generated by cloudlayer.io</p></body></html>' | base64)

curl -X POST "https://api.cloudlayer.io/v2/html/image" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d "{\"html\": \"$HTML_BASE64\"}"

Response:

{
  "id": "abc123",
  "status": "pending"
}

JavaScript (fetch)

const html = `<html>
  <body style="padding: 40px; font-family: Arial;">
    <h1 style="color: #2563eb;">Hello World</h1>
    <p>Generated by cloudlayer.io</p>
  </body>
</html>`;

const response = await fetch("https://api.cloudlayer.io/v2/html/image", {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    html: btoa(html),
  }),
});

const { id, status } = await response.json();
// Poll job status or use webhooks to know when the image is ready

Python (requests)

import base64
import requests

html = """<html>
  <body style="padding: 40px; font-family: Arial;">
    <h1 style="color: #2563eb;">Hello World</h1>
    <p>Generated by cloudlayer.io</p>
  </body>
</html>"""

response = requests.post(
    "https://api.cloudlayer.io/v2/html/image",
    headers={
        "X-API-Key": "your-api-key-here",
        "Content-Type": "application/json",
    },
    json={
        "html": base64.b64encode(html.encode()).decode(),
    },
)

job = response.json()
# Poll job status or use webhooks to know when the image is ready

Tip: v2 always returns JSON. Use the job id to poll the Jobs endpoint or configure Webhooks for completion notifications. The generated file is accessible via the Assets endpoint. Add "async": false to wait for processing to complete — the response is still JSON but includes the completed job details.

Parameters

Required

Parameter	Type	Description
`html`	string	Required. Base64-encoded HTML content. The HTML can include inline CSS, `<style>` tags, and `<link>` references to external stylesheets.

Image Parameters

These parameters control the image output format and processing.

Parameter	Type	Default	Description
`imageType`	string	`"png"`	Output image format. Options: `"png"`, `"jpg"`, `"jpeg"`, `"webp"`, or `"svg"`.
`quality`	number	—	Image quality (1-100). Only applies to `jpg`, `jpeg`, and `webp` formats.
`transparent`	boolean	`false`	Render with a transparent background. Only works with `"png"` and `"webp"` formats. Your HTML must not set a background color on the `<html>` or `<body>` elements.
`trim`	boolean	`false`	Trim whitespace from all edges of the resulting image. Useful for generating tightly-cropped screenshots of specific content.

Base Parameters

These parameters control page loading behavior, viewport configuration, and general output settings.

Parameter	Type	Default	Description
`autoScroll`	boolean	`false`	Scroll the page to the bottom before capturing. Triggers lazy-loaded content.
`delay`	number	`0`	Wait time in milliseconds after the page loads before capturing the image.
`filename`	string	—	Set the `Content-Disposition` filename on the response. Include the appropriate extension (e.g., `"screenshot.png"`).
`height`	string	—	Set the capture area height. Accepts CSS units (e.g., `"600px"`, `"100vh"`).
`width`	string	—	Set the capture area width. Accepts CSS units (e.g., `"800px"`, `"100vw"`).
`inline`	boolean	`false`	Display the image inline in the browser instead of triggering a download.
`landscape`	boolean	`false`	Render in landscape orientation.
`preferCSSPageSize`	boolean	`false`	Use CSS `@page` size for dimensions.
`projectId`	string	—	Associate with a project for dashboard organization.
`scale`	number	`1`	Page rendering scale (`0.1` to `2`). Higher values produce higher-resolution images.
`timeout`	number	`30000`	Maximum time in milliseconds to wait for the page to load.
`timeZone`	string	—	Browser timezone (IANA name, e.g., `"America/New_York"`).
`viewPort`	object	—	Browser viewport configuration. See HTML to PDF — viewPort.
`waitForSelector`	object	—	Wait for a CSS selector before capturing. See HTML to PDF — waitForSelector.
`waitUntil`	string	—	Navigation completion strategy: `"load"`, `"domcontentloaded"`, `"networkidle0"`, `"networkidle2"`.

Examples

Generate a WebP Image

curl -X POST "https://api.cloudlayer.io/v2/html/image" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d "{
    \"html\": \"$(echo '<h1>Hello</h1>' | base64)\",
    \"imageType\": \"webp\"
  }"

Transparent Background (PNG)

{
  "html": "PGRpdiBzdHlsZT0icGFkZGluZzogMjBweDsgZm9udC1zaXplOiAyNHB4OyI+VHJhbnNwYXJlbnQgQmFja2dyb3VuZDwvZGl2Pg==",
  "imageType": "png",
  "transparent": true,
  "trim": true
}

Important: When using transparent: true, make sure your HTML does not set background or background-color on the <html> or <body> elements. Any background color will override transparency.

High-Resolution Retina Image

Combine scale and viewPort.deviceScaleFactor for crisp, high-DPI images:

{
  "html": "...",
  "imageType": "png",
  "scale": 2,
  "viewPort": {
    "width": 1200,
    "height": 630,
    "deviceScaleFactor": 2
  }
}

Generate Open Graph images for social media sharing:

JavaScript (fetch)

const html = `<!DOCTYPE html>
<html>
<head>
  <style>
    body {
      margin: 0; padding: 0;
      width: 1200px; height: 630px;
      display: flex; align-items: center; justify-content: center;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      font-family: 'Arial', sans-serif;
      color: white;
    }
    .card {
      text-align: center;
      padding: 60px;
    }
    h1 { font-size: 56px; margin-bottom: 16px; }
    p { font-size: 24px; opacity: 0.9; }
  </style>
</head>
<body>
  <div class="card">
    <h1>${title}</h1>
    <p>${subtitle}</p>
  </div>
</body>
</html>`;

const response = await fetch("https://api.cloudlayer.io/v2/html/image", {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    html: btoa(html),
    imageType: "png",
    viewPort: {
      width: 1200,
      height: 630,
    },
    trim: false,
  }),
});

const job = await response.json();

Trimmed Element Screenshot

Capture just the content with no extra whitespace:

{
  "html": "...",
  "imageType": "png",
  "trim": true,
  "viewPort": {
    "width": 800,
    "height": 600
  }
}

Tips

Image dimensions: The output image size is determined by the viewport and content dimensions. Use viewPort to control the rendering area and width/height to set explicit capture dimensions.
Retina quality: Set scale: 2 or viewPort.deviceScaleFactor: 2 for crisp images on high-DPI displays. This doubles the pixel dimensions.
File size: Use "jpg" for photographs and complex images (smaller file size). Use "png" for graphics with text, logos, or transparency. Use "webp" for the best compression-to-quality ratio.
Transparency: Only works with "png" and "webp". Remove all background colors from your HTML/CSS.
Dynamic content: Use waitUntil: "networkidle0" and delay for pages that load charts, maps, or other dynamic content.

HTML to Image

Endpoint

Quick Start

Parameters

Required

Image Parameters

Base Parameters

Examples

Generate a WebP Image

Transparent Background (PNG)

High-Resolution Retina Image

Social Media Card (OG Image)

Trimmed Element Screenshot

Tips