# Ruby - HTML to Image Example

Generate PNG, JPG, or WebP images with Ruby, rendered in Google Chrome.

[Live demo](https://htmlcsstoimage.com/#demo) [Get an API key](https://htmlcsstoimage.com/dashboard)

## 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](/getting-started/using-the-api#creating-an-image).

## Ruby Example Code

Use the [HTML/CSS to Image Ruby client](https://github.com/htmlcsstoimage/ruby-client) to interact with the API.

Add this line to your application’s Gemfile:

```ruby
gem 'htmlcsstoimage-api'
```

**Initializing the API client**

```ruby
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.

```ruby
client = HTMLCSSToImage.new
```

**Creating an image**

```ruby
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.

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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](https://htmlcsstoimage.github.io/ruby-client/HTMLCSSToImage.html).

## Example with HTTParty

This example uses the [HTTParty gem](https://github.com/jnunemaker/httparty). Install with `gem install httparty`, or add it to your Gemfile.

```ruby
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.

```ruby
require "htmlcsstoimage"


def self.fetch_url(html:, css: nil, google_fonts: nil)
  cache_key = "htmlcssimage/#{Digest::SHA256.hexdigest([html, css, google_fonts].to_json)}"
  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: 24.hours)
  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.

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

Real-world example

See [dev.to’s social preview controller](https://github.com/thepracticaldev/dev.to/blob/9442fde9e799e0eaf82723550f29e0a677a0db2b/app/controllers/social_previews_controller.rb#L61) for an example of generating social cards.

## Need help?

Talk to a human. Email [support@htmlcsstoimage.com](mailto:support@htmlcsstoimage.com) and we’ll help you get started.