Official SDKv1.x

Ruby SDK

Official Ruby SDK for SnapSharp. Capture screenshots, generate OG images, and run site audits with gem install.

Installation

Install the Ruby SDK using your package manager:

shell

gem install snapsharp

Then import and initialise the client:

ruby

require "snapsharp"

snap = SnapSharp::Client.new("sk_live_...")

Replace sk_live_... with your API key from the dashboard.

Quick Start

Three common use cases to get you up and running in minutes.

1. Take a Screenshot

Capture a screenshot and save the binary data to a file.

ruby

require "snapsharp"

snap = SnapSharp::Client.new("sk_live_...")

image = snap.screenshot("https://example.com",
  width: 1280,
  height: 720,
  format: "png",
  full_page: false
)

File.binwrite("screenshot.png", image)
puts "Screenshot saved!"

2. Generate an OG Image

Create social-media-ready Open Graph images from any URL.

ruby

require "snapsharp"

snap = SnapSharp::Client.new("sk_live_...")

og = snap.og_image("https://example.com",
  template: "default",
  width: 1200,
  height: 630
)

File.binwrite("og-image.png", og)

3. Render HTML to Image

Pass raw HTML and optional CSS to produce a rendered image.

ruby

require "snapsharp"

snap = SnapSharp::Client.new("sk_live_...")

image = snap.html_to_image(
  "<h1>Hello World</h1><p>Rendered with SnapSharp</p>",
  width: 800,
  height: 400,
  format: "png",
  css: "body { font-family: sans-serif; background: #1a1a2e; color: #fff; display: grid; place-items: center; }"
)

File.binwrite("html-render.png", image)

API Reference

Complete list of methods available on the Ruby client.

screenshot

screenshot(url, **options) -> String

Captures a screenshot of the URL. Accepts width, height, format, full_page, device, dark_mode, delay, and headers options.

og_image

og_image(url, **options) -> String

Generates an Open Graph image using built-in or custom templates. Returns binary image data.

html_to_image

html_to_image(html, **options) -> String

Renders raw HTML/CSS to an image. Supports width, height, format, css, and transparent_bg.

site_audit

site_audit(url, **options) -> Hash

Runs a performance and SEO audit. Returns a Hash with performance, accessibility, SEO, and best practices scores.

All methods that return images accept an optional format parameter ("png", "jpeg", "webp"). Default is "png". See the full API reference for every available option.

Error Handling

The SDK throws typed errors with HTTP status, message, and a unique request ID for debugging. Always wrap calls in a try/catch to handle rate limits and authentication errors gracefully.

ruby

require "snapsharp"

snap = SnapSharp::Client.new("sk_live_...")

begin
  image = snap.screenshot("https://example.com")
rescue SnapSharp::APIError => e
  puts "Error #{e.status}: #{e.message}"
  puts "Request ID: #{e.request_id}"

  if e.status == 401
    puts "Invalid API key. Check your credentials."
  end
  if e.status == 429
    puts "Rate limited. Retry after #{e.retry_after}s"
  end
end

Status	Meaning	Action
400	Bad Request — invalid parameters	Check the request body and query params
401	Unauthorized — invalid or missing API key	Verify your API key in the dashboard
429	Too Many Requests — rate limit exceeded	Wait for `retryAfter` seconds
500	Internal Server Error	Retry with exponential back-off

Configuration

Customise the client with optional settings passed at initialisation.

ruby

snap = SnapSharp::Client.new("sk_live_...",
  base_url: "https://api.snapsharp.dev",  # Custom API base URL
  timeout: 30,                             # Request timeout in seconds
  retries: 2                               # Auto-retry on 5xx errors
)

Option	Default	Description
baseUrl	api.snapsharp.dev	Override the API base URL (e.g. for on-premise)
timeout	30s	Maximum time to wait for a response
retries	0	Number of automatic retries on 5xx errors

SDKs for other languages

Node.js Python PHP Go

Ready to start building?

Get your free API key and start capturing screenshots in under a minute. 100 free screenshots every month — no credit card required.

Get Free API Key Read the Docs