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": [
    "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": [
      "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: [
      "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": [
            "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.