URL to Image

Capture a screenshot of any web page as a PNG, JPG, or WebP image. Supports both simple GET requests and full-featured POST requests with authentication and cookies.

Endpoints

GET  /v1/url/image
POST /v1/url/image

The GET endpoint is a convenience method for simple screenshots. The POST endpoint supports the full range of parameters. All requests are processed synchronously — the response body is the raw image file.

GET  /v2/url/image
POST /v2/url/image

The GET endpoint is a convenience method for simple screenshots. The POST endpoint supports the full range of parameters. 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 (GET)

Capture a web page screenshot with a single GET request:

cURL

curl -X GET "https://api.cloudlayer.io/v1/url/image?url=https://example.com" \
  -H "X-API-Key: your-api-key-here" \
  --output screenshot.png

JavaScript (fetch)

const url = encodeURIComponent("https://example.com");

const response = await fetch(
  `https://api.cloudlayer.io/v1/url/image?url=${url}`,
  {
    headers: {
      "X-API-Key": "your-api-key-here",
    },
  }
);

const image = await response.arrayBuffer();

Python (requests)

import requests

response = requests.get(
    "https://api.cloudlayer.io/v1/url/image",
    params={"url": "https://example.com"},
    headers={"X-API-Key": "your-api-key-here"},
)

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

cURL

curl -X GET "https://api.cloudlayer.io/v2/url/image?url=https://example.com&async=false" \
  -H "X-API-Key: your-api-key-here" \
  --output screenshot.png

JavaScript (fetch)

const url = encodeURIComponent("https://example.com");

const response = await fetch(
  `https://api.cloudlayer.io/v2/url/image?url=${url}&async=false`,
  {
    headers: {
      "X-API-Key": "your-api-key-here",
    },
  }
);

const image = await response.arrayBuffer();

Python (requests)

import requests

response = requests.get(
    "https://api.cloudlayer.io/v2/url/image",
    params={"url": "https://example.com", "async": "false"},
    headers={"X-API-Key": "your-api-key-here"},
)

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

Quick Start (POST)

Use POST for full control over the screenshot:

cURL

curl -X POST "https://api.cloudlayer.io/v1/url/image" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "imageType": "webp",
    "viewPort": {
      "width": 1920,
      "height": 1080,
      "deviceScaleFactor": 2
    },
    "waitUntil": "networkidle0"
  }' \
  --output screenshot.webp

JavaScript (fetch)

const response = await fetch("https://api.cloudlayer.io/v1/url/image", {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    imageType: "webp",
    viewPort: {
      width: 1920,
      height: 1080,
      deviceScaleFactor: 2,
    },
    waitUntil: "networkidle0",
  }),
});

const image = await response.arrayBuffer();

Python (requests)

import requests

response = requests.post(
    "https://api.cloudlayer.io/v1/url/image",
    headers={
        "X-API-Key": "your-api-key-here",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com",
        "imageType": "webp",
        "viewPort": {
            "width": 1920,
            "height": 1080,
            "deviceScaleFactor": 2,
        },
        "waitUntil": "networkidle0",
    },
)

with open("screenshot.webp", "wb") as f:
    f.write(response.content)

cURL

curl -X POST "https://api.cloudlayer.io/v2/url/image" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "imageType": "webp",
    "viewPort": {
      "width": 1920,
      "height": 1080,
      "deviceScaleFactor": 2
    },
    "waitUntil": "networkidle0",
    "async": false
  }' \
  --output screenshot.webp

JavaScript (fetch)

const response = await fetch("https://api.cloudlayer.io/v2/url/image", {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    imageType: "webp",
    viewPort: {
      width: 1920,
      height: 1080,
      deviceScaleFactor: 2,
    },
    waitUntil: "networkidle0",
    async: false,
  }),
});

const image = await response.arrayBuffer();

Python (requests)

import requests

response = requests.post(
    "https://api.cloudlayer.io/v2/url/image",
    headers={
        "X-API-Key": "your-api-key-here",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com",
        "imageType": "webp",
        "viewPort": {
            "width": 1920,
            "height": 1080,
            "deviceScaleFactor": 2,
        },
        "waitUntil": "networkidle0",
        "async": False,
    },
)

with open("screenshot.webp", "wb") as f:
    f.write(response.content)

Tip: Omit "async": false to use the default async mode. The API will return a JSON response with the job ID immediately, and the generated image will be stored and accessible via the Assets endpoint.

GET Parameters

Parameter	Type	Required	Default	Description
`url`	string	Yes	—	The URL of the web page to capture. Must be URL-encoded.
`timeout`	number	No	`30000`	Maximum time in milliseconds to wait for the page to load.

POST Parameters

URL Parameters

Parameter	Type	Required	Default	Description
`url`	string	Yes	—	The URL of the web page to capture.
`authentication`	object	No	—	Credentials for HTTP Basic Authentication. See URL to PDF — authentication.
`cookies`	array	No	—	Cookies to set before navigating. See URL to PDF — cookies.

Image Parameters

Parameter	Type	Default	Description
`imageType`	string	`"png"`	Output image format: `"png"`, `"jpg"`, or `"webp"`.
`transparent`	boolean	`false`	Render with a transparent background. Only works with `"png"` and `"webp"`. The target page must not set a background color.
`trim`	boolean	`false`	Trim whitespace from all edges of the resulting image.

Base Parameters

Parameter	Type	Default	Description
`autoScroll`	boolean	`false`	Scroll the page to the bottom before capturing. Triggers lazy-loaded content and infinite scroll.
`delay`	number	`0`	Wait time in milliseconds after the page loads before capturing.
`filename`	string	—	Set the `Content-Disposition` filename on the response.
`height`	string	—	Set the capture area height with CSS units.
`width`	string	—	Set the capture area width with CSS units.
`inline`	boolean	`false`	Display the image inline in the browser instead of downloading.
`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`).
`timeout`	number	`30000`	Maximum time in milliseconds to wait for page load.
`timeZone`	string	—	Browser timezone (IANA name).
`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	`"networkidle2"`	Navigation completion strategy: `"load"`, `"domcontentloaded"`, `"networkidle0"`, `"networkidle2"`.

Examples

Mobile Screenshot

Capture the mobile version of a responsive website:

{
  "url": "https://example.com",
  "imageType": "png",
  "viewPort": {
    "width": 375,
    "height": 812,
    "deviceScaleFactor": 3,
    "isMobile": true,
    "hasTouch": true
  },
  "waitUntil": "networkidle0"
}

Full-Page Screenshot with Auto-Scroll

Capture the entire page, including below-the-fold content and lazy-loaded images:

{
  "url": "https://example.com/blog/long-article",
  "imageType": "jpg",
  "autoScroll": true,
  "waitUntil": "networkidle0",
  "delay": 1000
}

Authenticated Dashboard Screenshot

Capture a dashboard behind cookie-based authentication:

cURL

curl -X POST "https://api.cloudlayer.io/v2/url/image" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "cookies": [
      {
        "name": "session_token",
        "value": "abc123...",
        "domain": "app.example.com",
        "secure": true,
        "httpOnly": true
      }
    ],
    "imageType": "png",
    "viewPort": {
      "width": 1440,
      "height": 900
    },
    "waitUntil": "networkidle0",
    "delay": 2000,
    "filename": "dashboard-screenshot.png"
  }' \
  --output dashboard.png

High-Resolution Screenshot for Print

Generate a high-DPI screenshot suitable for print materials:

{
  "url": "https://example.com",
  "imageType": "png",
  "scale": 2,
  "viewPort": {
    "width": 1200,
    "height": 800,
    "deviceScaleFactor": 2
  },
  "waitUntil": "networkidle0"
}

Trimmed Element Capture

Capture just the rendered content with whitespace removed:

{
  "url": "https://example.com/widget",
  "imageType": "png",
  "trim": true,
  "transparent": true,
  "viewPort": {
    "width": 600,
    "height": 400
  }
}

Tips

Full-page screenshots: Use autoScroll: true to load all lazy content, then the renderer captures the full scrollable area.
Dynamic content: For SPAs and pages with charts/graphs, use waitUntil: "networkidle0" with a delay of 1-3 seconds to ensure all data has loaded and rendered.
File format choice: Use PNG for screenshots with text and sharp edges. Use JPG for photograph-heavy pages (smaller file size). Use WebP for the best balance of quality and compression.
Viewport matters: The default viewport is 1440x900. Set the viewport explicitly to control exactly what is captured, especially for responsive sites.
Transparent screenshots: Only works with PNG and WebP. The target page must have no background color set on <html> or <body>. Many sites set a white background, so transparency works best with your own HTML content via the HTML to Image endpoint.