Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
In Ruby, website screenshot APIs follow a simple pattern: install a provider’s gem, keep its credentials on the server, build a capture request with a public URL and rendering options, then save the returned bytes or use a generated image URL. For a documented SDK flow, ScreenshotOne provides a Ruby client with option validation and both URL-generation and binary-capture methods. For Rails workflows, html2img documents template rendering, Active Storage, background jobs and webhooks; Urlbox shows how to sign a request directly with HMAC-SHA256.
Choose a Ruby screenshot API by integration needs
There is no universally best provider for every Ruby app. Compare how each fits your Ruby version, output and deployment pattern. The examples below reflect the capabilities described in each provider’s documentation; confirm current gem releases, service limits and commercial terms before adopting one.
| Provider | Ruby package or approach | Documented fit |
|---|---|---|
| ScreenshotNeo | HTTP API; no Ruby-specific gem is required for the cURL, Python and Node examples available here. Ruby can make an HTTP GET request to its endpoint. | Cleaned screenshots, response billing/verdict headers, or use by an MCP-compatible AI client. |
| ScreenshotOne | screenshotone gem; ScreenshotOne::Client |
A compact SDK flow with an option builder, validation, generated capture URL or returned bytes, full-page capture, delay and geolocation. |
| html2img | html2img-client; Html2img::Client |
Ruby 3.1 or newer; Rails template rendering, selector capture, CSS injection, PDFs, Active Storage, retries and webhooks. |
| Urlbox | Ruby standard libraries: net/http, uri and openssl |
Low-level signed requests using HMAC-SHA256, with viewport and image options in its documented example. |
| ScreenshotAPI | screenshotapi_to; ScreenshotAPI::Client |
A client described as having no runtime dependencies, save/raw methods, typed errors and Rails/plain Ruby examples. |
| Screenshot Scout | screenshotscout; ScreenshotScout::Client |
An official gem with access/secret keys and a capture method; the documented requirement is Ruby 3.4 or newer. |
ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. Its API accepts a GET request with a URL and can return PNG, JPEG, WebP or PDF; its documented differentiators include removing supported consent banners and overlays before capture and billing only clean shots. See ScreenshotNeo for the service overview.
Capture an image with ScreenshotOne’s Ruby SDK
This example follows the documented client flow: install the gem, make a client with an access key (and optionally a secret key), configure a URL and capture options, validate, then write the returned bytes. Keep both credentials in server-side environment variables rather than committing them to source control.
- Add the dependency: put
gem "screenshotone"in your Gemfile and runbundle install. - Set credentials: provide
SCREENSHOTONE_ACCESS_KEY; setSCREENSHOTONE_SECRET_KEYif your account and signing setup use it. - Run a capture: save the following as a Ruby script and run it in the bundle context.
require "screenshotone"
client = ScreenshotOne::Client.new(
ENV.fetch("SCREENSHOTONE_ACCESS_KEY"),
ENV["SCREENSHOTONE_SECRET_KEY"]
)
options = ScreenshotOne::TakeOptions.new(url: "https://example.com")
.full_page(true)
.delay(2)
raise ArgumentError, "invalid options" unless options.valid?
File.binwrite("screenshot.jpg", client.take(options))The delay is in the example’s provider option builder; it gives the page time before capture, but it does not guarantee that every site has finished rendering. Use a URL the capture service can reach publicly. File.binwrite is intentional: screenshot data is binary, so writing it as text can corrupt the file.
#1 Best Overall
Return a generated URL instead of downloading bytes
If your flow needs a capture URL rather than an immediate local file, use the SDK’s URL-generation method:
capture_url = client.generate_take_url(options)
puts capture_urlChoose this when another server-side component will fetch the image or when you need to pass a URL onward. Treat generated URLs and any embedded credentials as sensitive; do not expose a secret key in browser code. The SDK’s documented onboarding note is: “Don’t forget to sign up to get access and secret keys.”
Add geolocation or adjust the capture
The documented ScreenshotOne options include full-page capture, a delay and geolocation latitude, longitude and accuracy. For example, the option builder can be extended with the provider’s geolocation methods when the page varies by location. Check the installed gem’s current option names and validation result before relying on less common settings; invalid combinations should be caught before sending the capture request.
Use html2img for Rails and production workflows
The html2img-client documentation requires Ruby 3.1 or newer and says the client reads HTML2IMG_API_KEY by default. Its documented capabilities include screenshots of public URLs, selector crops, CSS injection, full-page images, PDF rendering, CDN URLs, byte downloads, saved files and Active Storage attachments. It also describes rendering an Action View template into an image, which can be useful for app-generated cards or reports.
Rank #2
The client’s documented server-side warning is direct: “Keep your API key on the server. This client is designed for server-side use. Shipping your key in client-side code would let anyone spend your credits.” Configure the key in your deployment’s secret store or environment and keep API calls in server-side code.
Choose bytes, files, URLs or Active Storage
- Bytes: use when another Ruby method will transform or attach the image immediately.
- Saved file: use for a controlled local or temporary output path; account for cleanup and disk limits in workers.
- CDN URL: use when the provider-hosted result suits your delivery flow; confirm retention and access behavior with the provider before treating it as permanent storage.
- Active Storage: use the documented attachment integration when Rails owns the application’s asset workflow rather than writing arbitrary files from request handlers.
Move slow captures out of web requests
Browser rendering can take longer than a normal application response budget, especially for complex pages. The html2img documentation recommends background jobs for production work: retry server or connection errors, discard validation errors, and use webhooks when a render may outlast a synchronous request. This separates transient transport failures from bad input and avoids holding a user-facing request open while a remote browser works.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesMake jobs safe to retry. Associate each job with the target URL and the record that needs the result, avoid creating duplicate attachments on repeated delivery, and record terminal failures so an operator can see whether the URL, provider, or network caused the issue. A webhook should be verified and mapped back to the intended job before it updates application state.
Sign a Urlbox request with Ruby’s standard libraries
Urlbox’s Ruby example demonstrates a lower-level approach: construct a query, URL-encode it, calculate an HMAC-SHA256 token using the secret, then make an HTTP request with Net::HTTP. This avoids depending on a provider gem, but leaves query construction, signing and response handling to your application.
Rank #3
require "openssl"
require "uri"
require "net/http"
urlbox_key = ENV.fetch("URLBOX_API_KEY")
urlbox_secret = ENV.fetch("URLBOX_API_SECRET")
options = {
"url" => "https://example.com",
"full_page" => "true",
"format" => "png"
}
query_string = URI.encode_www_form(options)
token = OpenSSL::HMAC.hexdigest("sha256", urlbox_secret, query_string)
request_uri = URI("https://api.urlbox.io/v1/#{urlbox_key}/#{token}/png?#{query_string}")
response = Net::HTTP.get_response(request_uri)
unless response.is_a?(Net::HTTPSuccess)
raise "Screenshot request failed: HTTP #{response.code}"
end
File.binwrite("screenshot.png", response.body)Use the exact signing path and parameter names required by the current Urlbox endpoint and documentation for your account. A signature is calculated over the serialized query, so changing parameter order, encoding or values after signing can invalidate it. The provider’s example also describes optional force, thumbnail, viewport and quality values; add only parameters supported by the current endpoint and include them in the string before computing the HMAC.
What to evaluate beyond the first successful screenshot
A demo capture proves only that one request worked. Before selecting a provider for a service or Rails feature, compare the operational details that determine whether it fits your app:
- Runtime and installation: confirm the gem’s Ruby support against the production runtime. The documented html2img client requires Ruby 3.1+, while Screenshot Scout’s documentation says Ruby 3.4+.
- Credential model: determine whether the integration uses access and secret keys, a single server-side API key, or a signed URL. Keep secrets out of browser bundles and logs.
- Rendering controls: verify the needed viewport, full-page behavior, delay, geolocation, selector, CSS and image-quality controls. Do not assume an option on one SDK exists in another.
- Result handling: decide whether your code needs raw bytes, a file, a provider-hosted URL, or an attachment in Rails storage.
- Output format: check the exact formats required by downstream consumers. A PDF workflow has different needs from a thumbnail used in an
<img>element. - Failure model: look for typed errors, retry guidance, timeouts, asynchronous jobs and webhooks. Distinguish invalid capture options from transient network or provider failures.
- Cost and quota: verify current pricing, included credits, overage rules and cache behavior directly with the provider. These terms change and are not established by the SDK examples alone.
Or skip the browser setup
For a Ruby app, make a GET request to ScreenshotNeo’s endpoint and write the response body as binary. The following uses Ruby’s standard Net::HTTP; the complete parameter and response documentation is at ScreenshotNeo’s API docs.
require "net/http"
require "uri"
uri = URI("https://api.screenshotneo.com/v1/shot")
uri.query = URI.encode_www_form(
"access_key" => ENV.fetch("SCREENSHOTNEO_API_KEY"),
"url" => "https://stripe.com"
)
response = Net::HTTP.get_response(uri)
unless response.is_a?(Net::HTTPSuccess)
raise "ScreenshotNeo request failed: HTTP #{response.code}"
end
File.binwrite("shot.webp", response.body)
puts "Verdict: #{response["X-Page-Verdict"]}; billed: #{response["X-Billed"]}"Keep the API key server-side. ScreenshotNeo removes supported cookie/consent banners, newsletter popups and chat widgets before capture, with each cleanup step configurable. Bot checks, blank pages and failed loads are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server exposes screenshot and page-information tools for Claude, Cursor and other MCP clients. The free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo’s free plan.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common Ruby capture failures
Missing key or unexpected environment value
Symptom: the client cannot initialize, or the service rejects a request. Cause: the environment variable is absent, misspelled or not available to the process running the app or worker. Fix: verify the variable in that runtime’s secret configuration and use ENV.fetch where a missing credential should fail immediately. Do not print the key into logs while debugging.
Rank #4
Invalid options or a rejected signature
Symptom: a ScreenshotOne option fails validation or a signed Urlbox URL is rejected. Cause: unsupported or incompatible options, or a signature created from a query string different from the one sent. Fix: validate SDK options before capture; for HMAC requests, encode the final parameter set once, sign that exact serialized string and do not mutate it afterward.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Blank, incomplete or stale-looking output
Symptom: the saved file exists but content is missing or looks different from the browser. Cause: the target may need more time, may render content after load, may restrict automated access, or may depend on location or state. Fix: check that the URL is publicly reachable from the capture service, configure the provider’s supported delay or rendering controls, and provide required cookies, headers or geolocation where appropriate. A fixed delay is not a guarantee that a page has finished.
Corrupt image or a non-image saved as an image
Symptom: an image viewer cannot open the output. Cause: an error response or textual message was written as if it were image bytes, or text-mode handling altered the response. Fix: verify the HTTP response status before saving, inspect the provider’s response headers/body when a request fails, and use binary writes such as File.binwrite.
Requests time out in Rails
Symptom: a web request runs too long or a job fails intermittently. Cause: remote rendering may take longer than the application’s synchronous response window, or a temporary connection/server issue occurred. Fix: queue the work, set timeouts appropriate to the provider’s documented behavior, retry only transient failures with bounded attempts, and discard invalid inputs rather than retrying them. For long renders, use the documented webhook path where available.
Best Value
Access key appears in browser or logs
Symptom: a secret is visible in page source, client JavaScript or request logs. Cause: the API was called directly from an untrusted client or sensitive query strings were logged. Fix: proxy captures through server-side Ruby code, redact credentials and signed URLs from logs, and rotate exposed keys.
Frequently asked questions
Can Ruby capture a screenshot without a provider gem?
Yes. A Ruby program can make an HTTP request with standard libraries such as Net::HTTP, as in the ScreenshotNeo and Urlbox examples. A provider SDK can still reduce the work of assembling options and handling provider-specific response flows.
Can a screenshot API capture a URL that is only available on my laptop?
Not unless the capture service can reach it. For local development, expose a test environment through an access-controlled staging URL or use a provider feature that explicitly supports private-network access; do not assume an ordinary URL capture request can see localhost.
Are provider prices and quotas comparable from these SDK examples?
No. SDK documentation establishes integration patterns and some feature details, not a reliable cross-provider price or quota comparison. Check current vendor pricing and terms before budgeting.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
