RenderScreenshot

POST /v1/screenshot

The POST endpoint gives you full control over screenshot capture with all available options.

Endpoint

POST https://api.renderscreenshot.com/v1/screenshot

Authentication

Include your API key in the Authorization header:

Authorization: Bearer rs_live_xxxxx

Request Body

{
  "url": "https://example.com",
  "preset": "og_card",
  "viewport": {
    "width": 1200,
    "height": 630
  },
  "output": {
    "format": "png",
    "quality": 90
  }
}

Parameters

Parameter Type Required Description
url string Yes The URL to screenshot
preset string No Preset configuration (og_card, twitter_card, full_page, pdf_document)
viewport.width integer No Viewport width in pixels (default: 1280)
viewport.height integer No Viewport height in pixels (default: 720)
output.format string No Output format: png, jpeg, webp, pdf
output.quality integer No Image quality 1-100 (jpeg/webp only)
page.scripts array No JavaScript to inject (strings or {url} objects)
page.styles array No CSS to inject (strings or {url} objects)
page.click string No CSS selector to click before capture
page.hide array No Selectors to hide (visibility: hidden)
page.remove array No Selectors to remove from DOM
block.ads boolean No Block ad network requests
block.trackers boolean No Block analytics/tracking requests
block.cookie_banners boolean No Auto-dismiss cookie consent banners
block.chat_widgets boolean No Block chat widget requests
pdf.paper string No PDF paper size: letter, a4, legal, tabloid, etc.
pdf.landscape boolean No PDF landscape orientation
pdf.print_background boolean No Include background graphics (default: true)
pdf.margin string No Uniform margin (CSS units)
pdf.header string No HTML template for PDF header
pdf.footer string No HTML template for PDF footer
cache.available boolean No Return cached result if available (0 credits on hit)
cache.ttl integer No Cache duration in seconds (default: 86400, max: 2592000)
cache.refresh boolean No Bypass cache and force a fresh render
storage.enabled boolean No Upload to your storage bucket (default: true if configured)
storage.path string No Custom path template (e.g., {year}/{month}/{hash}.{ext})
storage.acl string No Access control: private or public-read

Response

On success, returns the screenshot binary with appropriate Content-Type header.

Headers

Content-Type: image/png  (or image/jpeg, image/webp, application/pdf)
X-Cache-URL: https://cdn.renderscreenshot.com/screenshots/abc123.png
X-Request-Id: req_xxxxx

The X-Cache-URL header contains a public CDN URL that requires no authentication.

Examples

Basic Screenshot

curl

curl -X POST https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com",
    "preset": "og_card"
  }' \
  --output screenshot.png

Java

import com.renderscreenshot.sdk.Client;
import com.renderscreenshot.sdk.TakeOptions;
import java.nio.file.Files;
import java.nio.file.Path;

Client client = new Client("rs_live_xxxxx");

byte[] image = client.take(
    TakeOptions.url("https://github.com").preset("og_card")
);

Files.write(Path.of("screenshot.png"), image);

Node.js

import { Client, TakeOptions } from 'renderscreenshot';
import { writeFile } from 'fs/promises';

const client = new Client('rs_live_xxxxx');

const image = await client.take(
  TakeOptions.url('https://github.com').preset('og_card')
);

await writeFile('screenshot.png', image);

PHP

use RenderScreenshot\Client;
use RenderScreenshot\TakeOptions;

$client = new Client('rs_live_xxxxx');

$image = $client->take(
    TakeOptions::url('https://github.com')->preset('og_card')
);

file_put_contents('screenshot.png', $image);

Python

from renderscreenshot import Client, TakeOptions

client = Client('rs_live_xxxxx')

image = client.take(
    TakeOptions.url('https://github.com').preset('og_card')
)

with open('screenshot.png', 'wb') as f:
    f.write(image)

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.renderscreenshot.com/v1/screenshot')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer rs_live_xxxxx'
request['Content-Type'] = 'application/json'
request.body = { url: 'https://github.com', preset: 'og_card' }.to_json

response = http.request(request)
File.binwrite('screenshot.png', response.body)

Generate PDF

curl

curl -X POST https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/report",
    "output": { "format": "pdf" },
    "pdf": {
      "paper": "a4",
      "print_background": true,
      "margin": "2cm"
    }
  }' \
  --output report.pdf

Java

import com.renderscreenshot.sdk.Client;
import com.renderscreenshot.sdk.TakeOptions;
import java.nio.file.Files;
import java.nio.file.Path;

Client client = new Client("rs_live_xxxxx");

byte[] pdf = client.take(
    TakeOptions.url("https://example.com/report")
        .format("pdf")
        .pdfPaperSize("a4")
        .pdfPrintBackground()
        .pdfMargin("2cm")
);

Files.write(Path.of("report.pdf"), pdf);

Node.js

import { Client, TakeOptions } from 'renderscreenshot';
import { writeFile } from 'fs/promises';

const client = new Client('rs_live_xxxxx');

const pdf = await client.take(
  TakeOptions.url('https://example.com/report')
    .format('pdf')
    .pdfPaperSize('a4')
    .pdfPrintBackground()
    .pdfMargin('2cm')
);

await writeFile('report.pdf', pdf);

PHP

use RenderScreenshot\Client;
use RenderScreenshot\TakeOptions;

$client = new Client('rs_live_xxxxx');

$pdf = $client->take(
    TakeOptions::url('https://example.com/report')
        ->format('pdf')
        ->pdfPaperSize('a4')
        ->pdfPrintBackground()
        ->pdfMargin('2cm')
);

file_put_contents('report.pdf', $pdf);

Python

from renderscreenshot import Client, TakeOptions

client = Client('rs_live_xxxxx')

pdf = client.take(
    TakeOptions.url('https://example.com/report')
    .format('pdf')
    .pdf_paper_size('a4')
    .pdf_print_background()
    .pdf_margin('2cm')
)

with open('report.pdf', 'wb') as f:
    f.write(pdf)

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.renderscreenshot.com/v1/screenshot')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer rs_live_xxxxx'
request['Content-Type'] = 'application/json'
request.body = {
  url: 'https://example.com/report',
  output: { format: 'pdf' },
  pdf: {
    paper: 'a4',
    print_background: true,
    margin: '2cm'
  }
}.to_json

response = http.request(request)
File.binwrite('report.pdf', response.body)

Full Parameter Reference

See Parameters for a complete list of all available options.

See Also

Was this page helpful?