Working with URLs

Convert any publicly accessible web page to a PDF or image by providing its URL. This is the simplest way to use cloudlayer.io, just pass a URL and get back a document.

Simple URL Capture

At its most basic, only a url parameter is required.

JSON Payload

{
  "url": "https://example.com"
}

cURL

curl --request POST \
  --url https://api.cloudlayer.io/v2/url/pdf \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --data '{
    "url": "https://example.com",
    "async": false
  }'

JavaScript

const response = await fetch("https://api.cloudlayer.io/v2/url/pdf", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR-API-KEY>",
  },
  body: JSON.stringify({
    url: "https://example.com",
    async: false,
  }),
});

const result = await response.json();
console.log("PDF URL:", result.assetUrl);

Python

import requests

response = requests.post(
    "https://api.cloudlayer.io/v2/url/pdf",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "<YOUR-API-KEY>",
    },
    json={
        "url": "https://example.com",
        "async": False,
    },
)

result = response.json()
print("PDF URL:", result["assetUrl"])

URL to Image

Use the /url/image endpoint instead:

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://example.com",
    "async": false
  }'

GET Request (Simple)

For quick captures with minimal options, use the GET endpoint:

curl --request GET \
  --url 'https://api.cloudlayer.io/v2/url/pdf?url=https://example.com&timeout=30000' \
  --header 'x-api-key: <YOUR-API-KEY>'

The GET endpoint only supports two parameters: url (required) and timeout (optional). Use the POST endpoint for all other options.

AutoScroll for Lazy-Loaded Content

Many modern websites use lazy loading, images and content only load when the user scrolls to them. The autoScroll option scrolls the page from top to bottom before capture, forcing all lazy-loaded content to load.

JSON Payload

{
  "url": "https://apple.com",
  "autoScroll": true
}

cURL

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://apple.com",
    "autoScroll": true,
    "async": false
  }'

JavaScript

const response = await fetch("https://api.cloudlayer.io/v2/url/image", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR-API-KEY>",
  },
  body: JSON.stringify({
    url: "https://apple.com",
    autoScroll: true,
    async: false,
  }),
});

const result = await response.json();
console.log("Image URL:", result.assetUrl);

Python

import requests

response = requests.post(
    "https://api.cloudlayer.io/v2/url/image",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "<YOUR-API-KEY>",
    },
    json={
        "url": "https://apple.com",
        "autoScroll": True,
        "async": False,
    },
)

result = response.json()
print("Image URL:", result["assetUrl"])

Viewport Configuration

Control the browser viewport dimensions used for rendering. This affects how the page layout responds to different screen sizes.

Desktop Viewport

{
  "url": "https://example.com",
  "viewPort": {
    "width": 1920,
    "height": 1080,
    "deviceScaleFactor": 2
  }
}

Mobile Viewport

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

Tablet Viewport

{
  "url": "https://example.com",
  "viewPort": {
    "width": 768,
    "height": 1024,
    "isMobile": true,
    "hasTouch": true,
    "deviceScaleFactor": 2
  }
}

Viewport Parameters

Waiting for Dynamic Content

waitForSelector

For single-page applications (SPAs) and pages with dynamically loaded content, use waitForSelector to wait for a specific element before capturing.

Wait for an element to appear:

{
  "url": "https://app.example.com/dashboard",
  "waitForSelector": {
    "selector": "#chart-container"
  }
}

Wait for an element to be visible:

{
  "url": "https://app.example.com/dashboard",
  "waitForSelector": {
    "selector": "#chart-container",
    "options": {
      "visible": true,
      "timeout": 15000
    }
  }
}

Wait for a loading spinner to disappear:

{
  "url": "https://app.example.com/report",
  "waitForSelector": {
    "selector": ".loading-spinner",
    "options": {
      "hidden": true,
      "timeout": 30000
    }
  }
}

waitForSelector Options

waitUntil

Control when the Chrome renderer considers the page “loaded” and begins conversion.

{
  "url": "https://example.com",
  "waitUntil": "networkidle0"
}

delay

Add a fixed delay (in milliseconds) after the page loads and before conversion begins. Useful when JavaScript-rendered content needs extra time.

{
  "url": "https://example.com",
  "waitUntil": "networkidle0",
  "delay": 3000
}

Batch URL Processing

Convert multiple URLs into a single combined PDF using the batch parameter. Each URL is converted to PDF individually, then all pages are merged into one document.

JSON Payload

{
  "batch": {
    "urls": [
      "https://example.com/page-1",
      "https://example.com/page-2",
      "https://example.com/page-3"
    ]
  }
}

Note: The batch parameter replaces the url parameter, do not use both.

cURL

curl --request POST \
  --url https://api.cloudlayer.io/v2/url/pdf \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR-API-KEY>' \
  --data '{
    "batch": {
      "urls": [
        "https://example.com/page-1",
        "https://example.com/page-2",
        "https://example.com/page-3"
      ]
    },
    "async": false
  }'

JavaScript

const response = await fetch("https://api.cloudlayer.io/v2/url/pdf", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR-API-KEY>",
  },
  body: JSON.stringify({
    batch: {
      urls: [
        "https://example.com/page-1",
        "https://example.com/page-2",
        "https://example.com/page-3",
      ],
    },
    async: false,
  }),
});

const result = await response.json();
console.log("Combined PDF URL:", result.assetUrl);

Python

import requests

response = requests.post(
    "https://api.cloudlayer.io/v2/url/pdf",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "<YOUR-API-KEY>",
    },
    json={
        "batch": {
            "urls": [
                "https://example.com/page-1",
                "https://example.com/page-2",
                "https://example.com/page-3",
            ],
        },
        "async": False,
    },
)

result = response.json()
print("Combined PDF URL:", result["assetUrl"])

Credit Usage

Batch processing uses multiple API credits:

• 1 credit per URL in the batch for individual PDF conversion
• 1 credit for the merge operation that combines all PDFs

For example, a batch of 3 URLs uses 4 credits total (3 conversions + 1 merge).

Common Options Reference

Tips

• Use autoScroll: true for image-heavy sites like portfolios, product pages, and social media feeds.
• Combine waitForSelector with waitUntil: "networkidle0" for the most reliable capture of JavaScript-heavy pages.
• Set printBackground: true for PDFs, background colors and images are omitted by default.
• Use a higher deviceScaleFactor (2 or 3) when generating images for high-DPI displays or print.
• For batch processing, use async mode with webhooks to avoid connection timeouts on large batches.
• If a page requires authentication, see the Authentication examples for Basic Auth and Cookie Auth methods.
• Set timeZone when capturing pages that display time-sensitive content to ensure consistent output across regions.