Use an SDK or the CLI

The SDKs build the request for you, send it, and turn errors into exceptions with a code you can check. Every SDK uses the same option names, so an example in one language reads the same in the others.

1Install the SDK

Node.js

npm install renderscreenshot

Python

# The package is not on PyPI yet. Install it from GitHub.
pip install git+https://github.com/Render-Screenshot/rs-python.git

Ruby

bundle add renderscreenshot

PHP

composer require renderscreenshot/renderscreenshot

Go

go get github.com/Render-Screenshot/rs-go

Java

// build.gradle, with the JitPack repository: maven { url 'https://jitpack.io' }
implementation 'com.github.Render-Screenshot:rs-java:v2.0.2'

2Create a client

Read the key from the environment. Create the client one time, when your app starts, and reuse it for every request.

Node.js

import { Client, TakeOptions } from 'renderscreenshot';

const client = new Client(process.env.RS_API_KEY);

Python

import os

from renderscreenshot import Client, TakeOptions

client = Client(os.environ['RS_API_KEY'])

Ruby

require 'renderscreenshot'

client = RenderScreenshot.client(ENV.fetch('RS_API_KEY'))

PHP

use RenderScreenshot\Client;
use RenderScreenshot\TakeOptions;

$client = new Client(getenv('RS_API_KEY'));

Go

client, err := rs.New(os.Getenv("RS_API_KEY"))
if err != nil {
    log.Fatal(err)
}

3Take a screenshot with options

Start with TakeOptions.url(...) and chain one method for each option. This call uses the og_card preset, blocks ads and turns on dark mode:

Node.js

import { writeFile } from 'node:fs/promises';

const image = await client.take(
  TakeOptions.url('https://renderscreenshot.com')
    .preset('og_card')
    .blockAds()
    .darkMode()
);
await writeFile('card.png', image);

Python

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

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

Ruby

image = client.take(
  RenderScreenshot::TakeOptions
    .url('https://renderscreenshot.com')
    .preset('og_card')
    .block_ads
    .dark_mode
)

File.binwrite('card.png', image)

PHP

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

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

Go

image, err := client.Take(context.Background(),
    rs.URL("https://renderscreenshot.com").Preset("og_card").BlockAds().DarkMode(),
)
if err != nil {
    log.Fatal(err)
}
os.WriteFile("card.png", image, 0o644)

The result is the image at the top of this guide. Each SDK reference page lists every option method, for example Node.js, Python and Ruby.

4Handle errors

A failed request raises one error class. Check code to decide what to do, and retry only when retryable is true. Failed requests use no credits.

Node.js

import { RenderScreenshotError } from 'renderscreenshot';

try {
  await client.take(TakeOptions.url('https://renderscreenshot.com').preset('og_card'));
} catch (error) {
  if (!(error instanceof RenderScreenshotError)) throw error;

  console.error(error.httpStatus, error.code, error.message);
  if (error.retryable) {
    // Try again later. For rate limits, wait error.retryAfter seconds first.
  }
}

Python

from renderscreenshot import RenderScreenshotError

try:
    client.take(TakeOptions.url('https://renderscreenshot.com').preset('og_card'))
except RenderScreenshotError as e:
    print(e.http_status, e.code, e.message)
    if e.retryable:
        pass  # Try again later. For rate limits, wait e.retry_after seconds first.

Ruby

begin
  client.take(RenderScreenshot::TakeOptions.url('https://renderscreenshot.com').preset('og_card'))
rescue RenderScreenshot::RateLimitError => e
  sleep(e.retry_after) if e.retry_after
  retry
rescue RenderScreenshot::Error => e
  warn "Screenshot failed: #{e.code} #{e.message} (request #{e.request_id})"
end

The codes you will see most often:

Prepare for production shows a complete retry loop.

5Use the CLI in scripts and CI

The rs command line tool takes the same options as flags. It reads the key from RS_API_KEY.

brew install render-screenshot/tap/rs
export RS_API_KEY=rs_live_your_key_here

rs take https://renderscreenshot.com --preset og_card --block-ads --dark-mode -o card.png

More flags you will use:

# The whole page, with cookie banners closed
rs take https://example.com --full-page --block-cookies -o page.png

# One element only
rs take https://example.com --element "main" -o main.png

# Wait for the page's own "ready" element before the capture
rs take https://example.com --wait-selector "#app-ready" -o ready.png

For Linux, Windows and CI install steps, see CLI installation and the CLI in CI.

Next steps

• Add social share images: the SDKs also make signed image URLs.
• Capture many pages at once with batch.
• Prepare for production.