Setting HTML content

You can set the HTML content of the page to render dynamically generated content.

danger

When this propriety is set, the url propriety must not be present.

Rest API (Without Stealth)

Here’s the request in the specified format, with examples for curl, JavaScript, Python, Java and C#.

Bot detection

Browserless recommends using our REST API to take screenshots, unless you need to get past bot detectors.

JSON payload

// JSON body
// `options` are the options available via puppeteer's Page.screenshot() method
// (see our Open API documentation)
{
  "html": "<h1>Hello World!</h1>",
  "options": {
    "type": "webp",
    "omitBackground": true
  }
}

cURL

curl -X POST \
  https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "html": "<h1>Hello World!</h1>",
  "options": {
    "type": "webp",
    "omitBackground": true
  }
}' \
  --output "screenshot.webp"

Javascript

import fs from 'fs/promises';

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/screenshot?token=${TOKEN}`;
const headers = {
  "Cache-Control": "no-cache",
  "Content-Type": "application/json"
};

const data = {
  html: "<h1>Hello World!</h1>",
  options: {
    type: "webp",
    omitBackground: true
  }
};

const takeScreenshot = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const imageBuffer = await response.arrayBuffer();
  await fs.writeFile("screenshot.webp", Buffer.from(imageBuffer));
  console.log("Screenshot saved as screenshot.webp");
};

takeScreenshot();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/screenshot?token={TOKEN}"
headers = {
    "Cache-Control": "no-cache",
    "Content-Type": "application/json"
}

data = {
    "html": "<h1>Hello World!</h1>",
    "options": {
        "type": "webp",
        "omitBackground": True
    }
}

response = requests.post(url, headers=headers, json=data)

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

print("Screenshot saved as screenshot.webp")

Java

import java.io.*;
import java.net.URI;
import java.net.http.*;
import java.nio.file.*;

public class TakeWebpScreenshot {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/screenshot?token=" + TOKEN;

        String jsonData = """
        {
            "html": "<h1>Hello World!</h1>",
            "options": {
                "type": "webp",
                "omitBackground": true
            }
        }
        """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Cache-Control", "no-cache")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<InputStream> response = client.send(request, HttpResponse.BodyHandlers.ofInputStream());
            Files.copy(response.body(), Paths.get("screenshot.webp"), StandardCopyOption.REPLACE_EXISTING);
            System.out.println("Screenshot saved as screenshot.webp");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/screenshot?token={TOKEN}";

        string jsonData = @"
          {
              ""html"": ""<h1>Hello World!</h1>"",
              ""options"": {
                  ""type"": ""webp"",
                  ""omitBackground"": true
              }
          }";

        using var client = new HttpClient();

        
        var request = new HttpRequestMessage(HttpMethod.Post, url)
        {
            Content = new StringContent(jsonData, Encoding.UTF8, "application/json")
        };

        
        request.Headers.Add("Cache-Control", "no-cache");

        try
        {
            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();

            var imageBytes = await response.Content.ReadAsByteArrayAsync();

            await File.WriteAllBytesAsync("screenshot.png", imageBytes);

            Console.WriteLine("Screenshot saved as screenshot.png");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

warning

We do not allow to set a options.path

BQL (Stealth)

If the /screenshot API is getting blocked by bot detectors, then we would recommend trying BrowserQL.

BQL Query

mutation Screenshot {
  content(html: "<h1>Hello, World!</h1>") {
    status
  }

  screenshot(type: webp) {
    base64
  }
}

cURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE' \
  --header 'Content-Type: application/json' \
  --data '{"query":"mutation Screenshot {\n  content(html: \"<h1>Hello, World!</h1>\") {\n    status\n  }\n\n  screenshot(type: webp) {\n    base64\n  }\n}","variables":"","operationName":"Screenshot"}'

Javascript

const endpoint = "https://production-sfo.browserless.io/chromium/bql";
const token = "YOUR_API_TOKEN_HERE";

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"query":"mutation Screenshot {\n  content(html: \"<h1>Hello, World!</h1>\") {\n    status\n  }\n\n  screenshot(type: webp) {\n    base64\n  }\n}","variables":"","operationName":"Screenshot"})
};

const url = `${endpoint}?token=${token}`;
const response = await fetch(url, options);
const data = await response.json();

console.log(data);

Python

import requests

endpoint = "https://production-sfo.browserless.io/chromium/bql"
query_string = {
    "token": "YOUR_API_TOKEN_HERE",
}
headers = {
    "Content-Type": "application/json",
}
payload = {
    "query": "mutation Screenshot {\n  content(html: \"<h1>Hello, World!</h1>\") {\n    status\n  }\n\n  screenshot(type: webp) {\n    base64\n  }\n}",
    "variables": None,
    "operationName": "Screenshot",
}

response = requests.post(endpoint, params=query_string, headers=headers, json=payload)
print(response.json())

Java

String url = "https://production-sfo.browserless.io/chromium/bql";
String token = "YOUR_API_TOKEN_HERE";
String endpoint = String.format("%s?token=%s%s%s", url, token);

HttpResponse<String> response = Unirest.post(endpoint)
    .header("Content-Type", "application/json")
    .body({"query":"mutation Screenshot {\n  content(html: \"<h1>Hello, World!</h1>\") {\n    status\n  }\n\n  screenshot(type: webp) {\n    base64\n  }\n}","variables":"","operationName":"Screenshot"})
    .asString();

C#

string url = "https://production-sfo.browserless.io/chromium/bql";
string token = "YOUR_API_TOKEN_HERE";
string endpoint = $"{url}?token={token}";

var payload = new
{
    query = @"mutation Screenshot {
  content(html: ""<h1>Hello, World!</h1>"") {
    status
  }

  screenshot(type: webp) {
    base64
  }
}",
    variables = "",
    operationName = "Screenshot"
};

using (var client = new HttpClient())
{
    // Serialize payload to JSON
    var json = System.Text.Json.JsonSerializer.Serialize(payload);

    // Build the request content
    var content = new StringContent(json, Encoding.UTF8, "application/json");

    // Send POST request
    var response = await client.PostAsync(endpoint, content);
    var responseBody = await response.Content.ReadAsStringAsync();

    // Print or use response as needed
    Console.WriteLine(responseBody);
}

BQL Schemas

For more details on BQL mutations, refer to the BrowserQL Schema reference pages.