Ruby SDK Examples for Website Screenshot APIs

Keep delays as short as the page requires. A delay allows client-side rendering to settle, while full-page mode captures content beyond the initial viewport.

3. Rails integration with html2img

The html2img Ruby client requires Ruby 3.1 or newer and reads HTML2IMG_API_KEY by default. It supports public URLs, selector crops, CSS injection, full-page images, PDFs, CDN URLs, byte downloads, file saves and Active Storage attachments.

# Gemfile
gem "html2img-client"

# shell
bundle install

A typical Rails service keeps the key on the server and asks the client for a capture. Consult the provider's current API reference for the exact method signature and output object for your installed release.

class WebsiteCapture
  def initialize(client: Html2img::Client.new)
    @client = client
  end

  def call(url:, selector: nil, css: nil)
    @client.capture(
      url: url,
      selector: selector,
      css: css,
      full_page: true
    )
  end
end

For an Action View template, render the template on the server and submit the resulting HTML through the client's Rails integration. For Active Storage, attach the returned bytes to a model after checking the response and content type.

Background jobs and webhooks

Screenshot rendering can exceed a web request budget. Put captures in Active Job or Sidekiq, retry transient server or connection errors, discard validation errors, and use a webhook for renders that may run longer than a synchronous request.

class CaptureWebsiteJob < ApplicationJob
  retry_on Net::ReadTimeout, wait: :exponentially_longer, attempts: 4
  retry_on Errno::ECONNRESET, wait: :exponentially_longer, attempts: 4

  discard_on ActiveRecord::RecordInvalid

  def perform(capture_id, url)
    capture = Capture.find(capture_id)
    result = WebsiteCapture.new.call(url: url)
    capture.file.attach(
      io: StringIO.new(result.bytes),
      filename: "capture-#{capture.id}.png",
      content_type: "image/png"
    )
    capture.update!(status: "complete")
  end
end

4. Urlbox: signed Ruby requests with HMAC-SHA256

Urlbox's low-level pattern uses openssl, uri and net/http. Build a query string, URL-encode the target URL and options, compute an HMAC-SHA256 digest with your secret, put the token in the API path, and retrieve PNG or JPG bytes.

require "openssl"
require "uri"
require "net/http"

key = ENV.fetch("URLBOX_KEY")
secret = ENV.fetch("URLBOX_SECRET")
target = "https://example.com"

params = {
  "url" => target,
  "full_page" => "true",
  "viewport" => "1280x800",
  "quality" => "80"
}
query = URI.encode_www_form(params)
token = OpenSSL::HMAC.hexdigest("sha256", secret, query)
uri = URI("https://api.urlbox.io/v1/#{key}/#{token}/png?#{query}")

bytes = Net::HTTP.get(uri)
File.binwrite("urlbox.png", bytes)

Sign the exact query string you send. Changing parameter order, encoding or values after calculating the digest causes signature failures.

5. Complete request options to plan for

6. cURL, Python and Node.js equivalents

The same architecture applies outside Ruby: send credentials from a server, pass a public URL, check the response, then persist bytes or a URL.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const buffer = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', buffer));

See the ScreenshotNeo documentation for request options and response details.

7. Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF. It accepts cookie and consent banners like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and lets you turn each cleanup step off. Bot checks, blank pages, timeouts, failed loads and cache hits cost nothing; response headers identify the page verdict and whether it was billed.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

It also supports full-page captures with lazy images loaded, CSS selector captures, dark mode, 12 device presets or custom viewports, retina scale, PDF controls, custom CSS and JavaScript, pre-capture clicks, waits, blocking rules, headers, cookies, user agents, Authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which helps migrations.

An MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients. Plans include 1,000 free shots per month with no card; paid plans start at $5 for 3,000 shots, and every feature is on every plan.

Create a free ScreenshotNeo account and start with 1,000 screenshots each month at no charge.

8. Secure credentials and request handling

• Store keys in environment variables or a server-side secret manager.
• Do not place provider keys in browser JavaScript, mobile apps or public repositories.
• Redact cookies, Authorization headers and signed URLs from logs.
• Validate target URLs to prevent your service from becoming an unrestricted fetch proxy.
• Set explicit connect and read timeouts and cap response sizes before writing files.
• Check HTTP status, content type and provider-specific error fields before treating a response as an image.

9. Reliability, performance and cost

Make captures predictable

• Use a fixed viewport, device, timezone and geolocation for repeatable output.
• Wait for a selector or network idle instead of adding a large blind delay.
• Prefer selector captures when a full page is unnecessary; they transfer fewer bytes.
• Enable caching with a deliberate TTL for pages that do not change often.
• Queue bulk or PDF work outside the request cycle and use webhooks for long renders.

Control spend

Provider pricing and quotas change, so verify current terms before committing. Track captures by URL, response status, format and cache outcome. ScreenshotNeo's billing model charges only clean shots; failed loads, bot checks, blank pages, timeouts and cache hits are not billed, and X-Page-Verdict and X-Billed headers explain each response.

10. Troubleshooting

11. Provider selection checklist

• Need the smallest Ruby example? Start with ScreenshotOne.
• Need Rails, Active Storage, CSS injection, PDFs, retries or webhooks? Evaluate html2img.
• Need explicit request signing? Use the Urlbox HMAC pattern.
• Need no runtime dependencies? Review ScreenshotAPI.
• Run Ruby 3.4 or newer and want another official gem? Review Screenshot Scout.
• Need consent cleanup, MCP access, predictable billing for failed pages or a low entry price? Try ScreenshotNeo first.

FAQ

Can Ruby save screenshot bytes directly?

Yes. ScreenshotOne's client.take(options) returns bytes that you can write with File.binwrite; other clients expose byte or download methods.

Should screenshot requests run in a controller?

Use a background job for slow pages, PDFs, bulk work or webhook-based workflows. A controller is suitable only when the rendering time fits your request timeout.

How do I capture a page that requires login?

Use a provider that accepts cookies, custom headers or Authorization, and keep those values on the server. Confirm that the service can reach the page and redact credentials from logs.

Is a browser gem required?

No. Hosted screenshot APIs run the browser remotely. ScreenshotNeo reduces the integration to an HTTP request and also provides MCP tools for AI agents.

What should I verify before publishing pricing?

Recheck each provider's current gem release, Ruby requirements, limits, pricing and commercial terms. Those details can change independently of the SDK interface.