Ruby: HTML/CSS to Image

Generate a png, jpg or webp images with Ruby. Renders exactly like Google Chrome.

Live demo Get an API Key

Generating images with Ruby

The API takes your HTML/CSS and runs it inside a real instance of Google Chrome to convert your html into an image. Use Ruby to send the API your HTML/CSS. You’ll get back the URL to your generated image.

For more details on how this works, see Creating an image.

Ruby Example Code

Use the HTML/CSS to Image Ruby client to interact with the API.

Add this line to your application’s Gemfile:

gem 'htmlcsstoimage-api'

Initializing the API client

require "htmlcsstoimage"

# Retrieve your user id and api key from https://htmlcsstoimage.com/dashboard
client = HTMLCSSToImage.new(user_id: "user-id", api_key: "api-key")

Alternatively, you can set ENV["HCTI_USER_ID"] and ENV["HCTI_API_KEY"]. These will be loaded automatically.

client = HTMLCSSToImage.new

Creating an image

image = client.create_image("<div>Hello, world</div>",
                            css: "div { background-color: red; font-family: Roboto; }",
                            google_fonts: "Roboto")

image
=> #<HTMLCSSToImage::ApiResponse url="https://hcti.io/v1/image/254b444c-dd82-4cc1-94ef-aa4b3a6870a6", id="254b444c-dd82-4cc1-94ef-aa4b3a6870a6">
image.url
=> "https://hcti.io/v1/image/254b444c-dd82-4cc1-94ef-aa4b3a6870a6"

Creating and deleting images in batches

Create several HTML/CSS or URL images in one API request. Values in the second argument are shared defaults that each variation can override.

images = client.create_image_batch(
  [
    { html: "<h1>First image</h1>" },
    { html: "<h1>Second image</h1>", transparent_background: true }
  ],
  { viewport_width: 1200 }
)

Delete several images by ID:

client.delete_image_batch([
  "254b444c-dd82-4cc1-94ef-aa4b3a6870a6",
  "60ab90f0-c019-4d0d-a234-cc39e1f2226e"
])

Generating signed image URLs

Signed URLs render images on demand without exposing your API key. Generate them in trusted server-side code.

Create a signed URL for a webpage screenshot:

signed_image = client.generate_create_and_render_url(
  "https://example.com/dashboard",
  viewport_width: 1200,
  viewport_height: 630,
  transparent_background: false
)

signed_image.url

Create a signed URL for a saved template:

signed_image = client.generate_templated_image_url(
  "t-56c64be5-5861-4148-acec-aaaca452027f",
  { title: "Hello, world!" },
  template_version: 1596829374001
)

signed_image.url

Custom headers used with generate_create_and_render_url are visible in the generated URL. Do not include long-lived credentials.

Template signature change in 0.2.0

Ruby client 0.1.x URL-decoded the template query string before generating its HMAC. Version 0.2.0 signs the encoded query string exactly as it appears after ?, as required by the current API.

Regenerating a template URL with the same inputs after upgrading produces a different token. Existing URLs generated by 0.1.x continue to work.

To see additional methods available with the Ruby gem, see the documentation here.

Example with HTTParty

This example uses the HTTParty gem. Install with gem install httparty, or add it to your Gemfile.

require "httparty"
# Retrieve your user id and api key from the Dashboard
auth = { username: 'user_id', password: 'api_key' }

html = "<div class='ping'>Pong ✅</div>"
css = ".ping { padding: 20px; font-family: 'sans-serif'; }"

image = HTTParty.post("https://hcti.io/v1/image",
                      body: { html: html, css: css },
                      basic_auth: auth)

# => {"url"=>"https://hcti.io/v1/image/bde7d5bf-f7bb-49d9-b931-74e5512b8738"}

Ruby on Rails example with caching

This example uses Rails built in caching.

• The cache key is a SHA of your html/css and google fonts.
• You’ll only generate a unique image once.
• If your HTML changes at all, a new image will be created. Subsequent calls using the same HTML/CSS parameters will return the cached URL rather than creating a new image.

require "htmlcsstoimage"

def self.fetch_url(html:, css: nil, google_fonts: nil)
  cache_key = "htmlcssimage/#{html}/#{css}/#{google_fonts}"
  cached_url = Rails.cache.read(cache_key)

  return cached_url if cached_url.present?

  client = HTMLCSSToImage.new
  image = client.create_image(html, css: css, google_fonts: google_fonts)

  if image.url
    Rails.cache.write(cache_key, image.url, expires_in: CACHE_EXPIRATION)
  end

  image.url
end

Rendering a Rails view

This can be useful from within a controller. To render a view from Rails and pass it to the API, use render_to_string from within a controller action.

With this, you can create an image from a template and redirects the user to the image.

html = render_to_string("path/to/view", formats: :html, layout: false)
redirect_to fetch_url(html: html, google_fonts: "Roboto|Roboto+Condensed"), status: :found

Need help?

Talk to a human. Please email us support@htmlcsstoimage.com with any questions and we’ll gladly help you get started.