{: .no_toc } {: .fs-9 }

Generate a png, jpg or webp images with Ruby. Renders exactly like Google Chrome. {: .fs-6 .fw-300 }

Live demo{: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 target="_blank" } Get an API Key{: .btn .fs-5 .mb-4 .mb-md-0 target="_blank" }

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.

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"

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"
])

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.

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.

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"}

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

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

{% include hint.md title="Real world example" text="Take a look at dev.to's source code to see how they implemented this for generating social cards. Code on GitHub." %}

{% include code_footer.md version=1 %}