htmlcsstoimage-api 0.1.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c33bcd3c7a212ce188b7016c5910a5053f801005a2eb93d367b2cc2722a98aee
-  data.tar.gz: de1d090df2591e9c37b2a60b9331b83cb700c106e971782d2bce16345086e6cc
+  metadata.gz: 38df32b2223110a9e3a096a56984fa3f3bb4ec963193c9cf4cea7f078e9026c3
+  data.tar.gz: 28bdef1535be738ebc2ddbbab194f7ac51cd0fc416edb071c623d6efdc320cc8
 SHA512:
-  metadata.gz: eaebdc8ab7326430a86bbca299376e94cf890ba4f7e4bceaf2b7aa7e4ef18d974ce3223defba69015dcccfaf78bc1ed2aa101069d626f36130d53b55f5633f83
-  data.tar.gz: 490e852085597ab9c65bf6c9a812853f3585a5c4c9ec0a26a0a816dba86d64e3db436249ff6bcf77d360c770828728685ca2d0a3392b8f6c3a8dade3ec092d1d
+  metadata.gz: 84a023aaaab14f26092d3f6da4d1d41edec173462488287bbbb7a951bf861cfe73590009e8342c5c77fe85cbfb917045d2ebb8833d3d0cb5a263dad2b3369d00
+  data.tar.gz: bf9e8f408a9c622bf5f17c91c45ac4834379e4b354379afe98c6f6ba5eda01e89316ce62fe4203fdcb39ed90ac5840d5b92ebc2d9c36440a126a915580f4be20

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    htmlcsstoimage-api (0.1.3)
+    htmlcsstoimage-api (0.3.0)
       addressable (> 2.5.0)
       httparty (> 0.10)
 
@@ -56,6 +56,7 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.45)
 
 PLATFORMS
   ruby
@@ -69,6 +70,7 @@ DEPENDENCIES
   rspec (~> 3.0)
   vcr
   webmock
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.5.23

data/README.md

@@ -4,7 +4,7 @@
 
 Ruby client for the [HTML/CSS to Image API](https://htmlcsstoimage.com).
 
-Generate png, jpg or webp images with Ruby. Renders exactly like Google Chrome.
+Generate PNG, JPG, WebP, or PDF files with Ruby. Renders exactly like Google Chrome.
 
 ## Installation
 
@@ -42,12 +42,14 @@ client = HTMLCSSToImage.new
 ```
 
 ### Create an image
+
 Generate an image from HTML/CSS. Returns a URL to the image.
 
 ```ruby
 image = client.create_image("<div>Hello, world</div>",
                             css: "div { background-color: red; font-family: Roboto; }",
-                            google_fonts: "Roboto")
+                            google_fonts: "Roboto",
+                            format: "webp")
 
 image
 => #<HTMLCSSToImage::ApiResponse url="https://hcti.io/v1/image/254b444c-dd82-4cc1-94ef-aa4b3a6870a6", id="254b444c-dd82-4cc1-94ef-aa4b3a6870a6">
@@ -56,20 +58,164 @@ image.url
 ```
 
 ### Delete an image
+
 Delete an existing image. Removes the image from HCTI servers and clears the CDN.
 
 ```ruby
 client.delete_image("254b444c-dd82-4cc1-94ef-aa4b3a6870a6")
 ```
 
+Delete several images in one request:
+
+```ruby
+client.delete_image_batch([
+  "254b444c-dd82-4cc1-94ef-aa4b3a6870a6",
+  "60ab90f0-c019-4d0d-a234-cc39e1f2226e"
+])
+```
+
 ### URL to image
+
 Generate a screenshot of any public URL.
 
 ```ruby
 image = client.url_to_image("https://github.com", viewport_width: 800, viewport_height: 1200)
 ```
 
+### Create a PDF
+
+Select PDF output with `format: "pdf"`; use `pdf_options` to configure its layout:
+
+```ruby
+pdf = client.create_image(
+  "<h1>Quarterly report</h1>",
+  format: "pdf",
+  pdf_options: {
+    print_background: true,
+    margins: ["20px", "20px", "20px", "20px"]
+  }
+)
+```
+
+### Create a batch of images
+
+Create several HTML/CSS or URL images in one API request. Each variation inherits
+values from `default_options` and can override them.
+
+```ruby
+images = client.create_image_batch(
+  [
+    { html: "<h1>First</h1>", format: "jpg" },
+    { html: "<h1>Second</h1>", transparent_background: true }
+  ],
+  { viewport_width: 1200, format: "webp" }
+)
+```
+
+## Signed URLs
+
+Signed URLs let another application, browser, or service render an image on
+demand without exposing your API key. Generating a signed URL does not make an
+API request; the image is created when the resulting URL is requested.
+
+Both signed URL methods return an `HTMLCSSToImage::ApiResponse`. Use `.url` to
+retrieve the URL:
+
+```ruby
+signed_image = client.generate_create_and_render_url("https://example.com")
+signed_image.url
+# => "https://hcti.io/v1/image/create-and-render/user-id/..."
+```
+
+Generate signed URLs in trusted server-side code. The API key is used to create
+the HMAC signature and should never be exposed to a browser or end user. Query
+parameters are covered by that signature, so modifying them after generation
+invalidates the URL. Remember that the URL and its query values remain visible
+to anyone who receives it.
+
+[Learn more about create-and-render and signed URLs](https://docs.htmlcsstoimage.com/getting-started/create-and-render/).
+
+### Sign a URL screenshot
+
+Use `generate_create_and_render_url` when you want HCTI to capture a public
+webpage each time the signed URL is requested. Pass the target URL first,
+followed by the same screenshot options accepted by `url_to_image`.
+
+```ruby
+signed_image = client.generate_create_and_render_url(
+  "https://example.com/dashboard",
+  css: ".navigation { display: none; }",
+  headers: { "X-Preview-Mode" => "enabled" },
+  additional_header_origins: ["https://api.example.com"],
+  include_headers_on_subrequests: true,
+  identify_as_hcti: true,
+  format: "webp",
+  viewport_width: 1200,
+  viewport_height: 630,
+  transparent_background: false
+)
+
+signed_image.url
+# => "https://hcti.io/v1/image/create-and-render/user-id/..."
+```
+
+`pdf_options` is not supported by the create-and-render endpoint and
+`dedupe_duration_s` only applies to standard POST requests, so both are omitted
+when generating this URL. Other boolean options set to `false` are omitted,
+except `transparent_background`, where both `true` and `false` are meaningful.
+Custom headers are encoded in the URL and must not contain long-lived secrets.
+
+### Sign a templated image
+
+Use `generate_templated_image_url` to substitute values into a saved template
+when the signed URL is requested. Pass `template_version` to pin the URL to a
+specific version; omit it to use the latest template version.
+
+```ruby
+signed_image = client.generate_templated_image_url(
+  "t-56c64be5-5861-4148-acec-aaaca452027f",
+  {
+    title: "Hello, world!",
+    customer: {
+      name: "Ada",
+      plan: "Pro"
+    }
+  },
+  template_version: 1596829374001,
+  format: "webp"
+)
+
+signed_image.url
+# => "https://hcti.io/v1/image/t-56c64be5-.../signed-token?template_version=...&customer=...&title=..."
+```
+
+Hashes and arrays in `template_values` are serialized as JSON. Values set to
+`nil` are omitted from the signed query string.
+
+#### Changed in 0.2.0: template URL signatures
+
+Ruby client 0.1.x URL-decoded the query string before generating its HMAC.
+Version 0.2.0 instead signs the encoded query string exactly as it appears in
+the generated URL, as required by the current API.
+
+This means regenerating a template URL with the same inputs produces a
+different token after upgrading from 0.1.x. Previously generated URLs are not
+modified and continue to work.
+
+`create_image_from_template` remains available as a compatibility proxy:
+
+```ruby
+signed_image = client.create_image_from_template(
+  "t-56c64be5-5861-4148-acec-aaaca452027f",
+  { title: "Hello, world!" }
+)
+```
+
+Its legacy third argument was previously ignored. It remains unsupported except
+for `template_version`; other keys in that argument are ignored.
+
 ## Templates
+
 A template allows you to define HTML that includes variables to be substituted at the time of image creation. [Learn more about templates](https://docs.htmlcsstoimage.com/getting-started/templates/).
 
 ```ruby
@@ -77,22 +223,45 @@ template = client.create_template("<div>{{title}}</div>")
 # => #<HTMLCSSToImage::ApiResponse template_id="t-56c64be5-5861-4148-acec-aaaca452027f", template_version=1596829374001>
 
 # Get templates
-all_templates = client.templates
-
-# Create a signed URL for a templated image
-image = client.create_image_from_template(template.template_id, { title: "Hello, world!" })
-# => #<HTMLCSSToImage::ApiResponse url="https://hcti.io/v1/image/t-56c64be5-5861-4148-acec-aaaca452027f/3aaa814dd998b302cc62b3550ddb35e8b9117c5ecea286da904eced0a3f44d9e?title=Hello%2C%20world%21">
-
-image.url
-# => "https://hcti.io/v1/image/t-56c64be5-5861-4148-acec-aaaca452027f/3aaa814dd998b302cc62b3550ddb35e8b9117c5ecea286da904eced0a3f44d9e?title=Hello%2C%20world%21"
+all_templates = client.list_templates(count: 25)
+
+# Get versions of one template
+versions = client.list_template_versions(template.template_id, count: 25)
+
+# Create a new version
+version = client.create_template_version(
+  template.template_id,
+  "<div class='updated'>{{title}}</div>"
+)
+
+# Create a templated image with an API request
+created_image = client.create_templated_image(
+  template.template_id,
+  { title: "Hello, world!" },
+  template_version: version.template_version,
+  format: "webp"
+)
 ```
 
+For signed, on-demand template images, see “Sign a templated image” in the
+Signed URLs section above. `templates` remains available as a compatibility
+alias for `list_templates`.
+
 ### Additional methods
+
 See the [ruby-client docs for all of the available methods](https://htmlcsstoimage.github.io/ruby-client/HTMLCSSToImage.html).
 
 ## Available parameters
+
 For detailed information on all the available parameters, visit the docs: https://docs.htmlcsstoimage.com/getting-started/using-the-api/
 
+The client passes supported API parameters through as JSON. Recent additions
+include `dedupe_duration_s`, `storage_destination_id`,
+`transparent_background`, `format`, `proxy_id`, `jumbo_max_width`, `jumbo_max_height`,
+and, for URL screenshots, `headers`, `additional_header_origins`,
+`include_headers_on_subrequests`, `identify_as_hcti`, and
+`block_consent_banners`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -102,6 +271,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 To generate the Yard docs, run `yard doc -o docs` and commit the changes.
 
 ## Support
+
 For help with the API, you can also contact `support@htmlcsstoimage.com`.
 
 ## Contributing

data/htmlcsstoimage.gemspec

@@ -10,14 +10,15 @@ Gem::Specification.new do |spec|
   spec.email         = ["support@htmlcsstoimage.com"]
 
   spec.summary       = %q{Ruby client for the HTML/CSS to Image API.}
-  spec.description   = %q{Ruby client for the HTML/CSS to Image API. Generate a png, jpg or webp images with Ruby. Renders exactly like Google Chrome. }
+  spec.description   = %q{Ruby client for the HTML/CSS to Image API. Generate PNG, JPG, WebP, or PDF files with Ruby. Renders exactly like Google Chrome. }
   spec.homepage      = "https://docs.htmlcsstoimage.com/example-code/ruby"
   spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|doc)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|doc|docs|cassettes)/}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
@@ -32,4 +33,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pry-byebug"
   spec.add_development_dependency "vcr"
   spec.add_development_dependency "webmock"
+  spec.add_development_dependency "yard", "~> 0.9"
 end

data/lib/htmlcsstoimage/client.rb

@@ -0,0 +1,36 @@
+# Client for creating images and managing templates with HTML/CSS to Image.
+class HTMLCSSToImage
+  include HTTParty
+
+  base_uri "https://hcti.io"
+  headers "Content-Type" => "application/json"
+  format :json
+
+  # A structured API response with attribute-style access to JSON fields.
+  class ApiResponse < OpenStruct
+  end
+
+  parser(
+    proc do |body, format|
+      case format
+      when :json
+        JSON.parse(body, object_class: ApiResponse)
+      else
+        body
+      end
+    end
+  )
+
+  # Creates an instance of HTMLCSSToImage with API credentials.
+  # If credentials are not provided, the client uses the `HCTI_USER_ID`
+  # and `HCTI_API_KEY` environment variables.
+  #
+  # @see https://htmlcsstoimage.com/dashboard
+  #
+  # @param user_id [String] the user ID for the account
+  # @param api_key [String] the API key for the account
+  # @return [HTMLCSSToImage] an instance of the API client
+  def initialize(user_id: ENV["HCTI_USER_ID"], api_key: ENV["HCTI_API_KEY"])
+    @auth = { username: user_id, password: api_key }
+  end
+end

data/lib/htmlcsstoimage/images.rb

@@ -0,0 +1,173 @@
+class HTMLCSSToImage
+  # Converts HTML/CSS to an image with the API.
+  #
+  # @see https://docs.htmlcsstoimage.com/getting-started/using-the-api
+  #
+  # @param html [String] HTML to render, as a snippet or an entire webpage
+  # @param params [Hash] image creation options
+  # @option params [String] :format The format used in the initially returned URL: `png`, `jpg`, `webp`, or `pdf`. This does not change the stored image definition or prevent rendering another supported format later.
+  # @option params [String] :css The CSS for your image.
+  # @option params [Numeric] :device_scale The pixel ratio for the screenshot. Minimum: `0.1`, Maximum: `3`.
+  # @option params [String] :google_fonts Google Fonts to load. Separate multiple fonts with `|`.
+  # @option params [Integer] :max_wait_ms The maximum time to wait before taking the screenshot. Minimum: `500`, Maximum: `10000`.
+  # @option params [Integer] :ms_delay Extra time in milliseconds to wait before taking the screenshot. Maximum: `10000`.
+  # @option params [Boolean] :render_when_ready Wait until `ScreenshotReady()` is called from JavaScript before taking the screenshot.
+  # @option params [String] :selector A CSS selector for the element to capture.
+  # @option params [Integer] :viewport_height The Chrome viewport height. Both viewport dimensions must be set if using either.
+  # @option params [Integer] :viewport_width The Chrome viewport width. Both viewport dimensions must be set if using either.
+  # @option params [Hash] :pdf_options Options for generating a PDF, including page size, margins, scale, and background printing.
+  # @option params [Boolean] :disable_twemoji Disable the Twemoji fallback and use native emoji fonts.
+  # @option params [Boolean] :max_render_once Ensure the image is only rendered and saved once.
+  # @option params [Integer] :dedupe_duration_s Reuse an identical image created within this many seconds. Only supported for single-image POST requests.
+  # @option params [String] :color_scheme Render using the `light` or `dark` browser color scheme.
+  # @option params [String] :timezone The browser timezone as an IANA timezone identifier, such as `America/New_York`.
+  # @option params [Boolean] :viewport_mobile Whether to honor the page's mobile viewport behavior.
+  # @option params [Boolean] :viewport_landscape Whether to render the viewport in landscape mode.
+  # @option params [Boolean] :viewport_touch Whether the viewport supports touch events.
+  # @option params [String] :media_type Render using `print` or `screen` media.
+  # @option params [String] :proxy_id The ID of an organization proxy to use for the render.
+  # @option params [String] :storage_destination_id The ID of an organization storage destination for the rendered image.
+  # @option params [Integer] :jumbo_max_height Maximum output height in jumbo mode. Requires `jumbo_max_width`.
+  # @option params [Integer] :jumbo_max_width Maximum output width in jumbo mode. Requires `jumbo_max_height`.
+  # @option params [Boolean] :transparent_background Whether to render the image with a transparent background.
+  # @return [HTMLCSSToImage::ApiResponse] image details, including `.url`
+  def create_image(html, params = {})
+    body = { html: html }.merge(params).to_json
+    options = { basic_auth: @auth, body: body, query: { includeId: true } }
+
+    self.class.post("/v1/image", options)
+  end
+
+  # Generates a screenshot of a public URL.
+  #
+  # @see https://docs.htmlcsstoimage.com/getting-started/url-to-image/
+  #
+  # @param url [String] the fully qualified URL to capture
+  # @param params [Hash] image creation options
+  # @option params [String] :format The format used in the initially returned URL: `png`, `jpg`, `webp`, or `pdf`. This does not change the stored image definition or prevent rendering another supported format later.
+  # @option params [String] :css CSS to inject into the webpage.
+  # @option params [Numeric] :device_scale The pixel ratio for the screenshot. Minimum: `0.1`, Maximum: `3`.
+  # @option params [Boolean] :full_screen Take a screenshot of the entire scrollable page.
+  # @option params [Integer] :max_wait_ms The maximum time to wait before taking the screenshot. Minimum: `500`, Maximum: `10000`.
+  # @option params [Integer] :ms_delay Extra time in milliseconds to wait before taking the screenshot. Maximum: `10000`.
+  # @option params [Boolean] :render_when_ready Wait until `ScreenshotReady()` is called from JavaScript before taking the screenshot.
+  # @option params [String] :selector A CSS selector for the element to capture.
+  # @option params [Integer] :viewport_height The Chrome viewport height. Both viewport dimensions must be set if using either.
+  # @option params [Integer] :viewport_width The Chrome viewport width. Both viewport dimensions must be set if using either.
+  # @option params [Hash] :pdf_options Options for generating a PDF, including page size, margins, scale, and background printing.
+  # @option params [Boolean] :disable_twemoji Disable the Twemoji fallback and use native emoji fonts.
+  # @option params [Boolean] :max_render_once Ensure the image is only rendered and saved once.
+  # @option params [Integer] :dedupe_duration_s Reuse an identical image created within this many seconds. Only supported for single-image POST requests.
+  # @option params [String] :color_scheme Render using the `light` or `dark` browser color scheme.
+  # @option params [String] :timezone The browser timezone as an IANA timezone identifier, such as `America/New_York`.
+  # @option params [Boolean] :block_consent_banners Attempt to block cookie and consent banners.
+  # @option params [Hash{String => String}] :headers Custom HTTP headers to send to allowed origins.
+  # @option params [Array<String>] :additional_header_origins Additional exact origins allowed to receive custom headers.
+  # @option params [Boolean] :include_headers_on_subrequests Send custom headers on subrequests to allowed origins.
+  # @option params [Boolean] :identify_as_hcti Add `X-HCTI-SCREENSHOT: 1` to the top-level page request.
+  # @option params [Boolean] :viewport_mobile Whether to honor the page's mobile viewport behavior.
+  # @option params [Boolean] :viewport_landscape Whether to render the viewport in landscape mode.
+  # @option params [Boolean] :viewport_touch Whether the viewport supports touch events.
+  # @option params [String] :media_type Render using `print` or `screen` media.
+  # @option params [String] :proxy_id The ID of an organization proxy to use for the render.
+  # @option params [String] :storage_destination_id The ID of an organization storage destination for the rendered image.
+  # @option params [Integer] :jumbo_max_height Maximum output height in jumbo mode. Requires `jumbo_max_width`.
+  # @option params [Integer] :jumbo_max_width Maximum output width in jumbo mode. Requires `jumbo_max_height`.
+  # @option params [Boolean] :transparent_background Whether to render the image with a transparent background.
+  # @return [HTMLCSSToImage::ApiResponse] image details, including `.url`
+  def url_to_image(url, params = {})
+    body = { url: url }.merge(params).to_json
+    options = { basic_auth: @auth, body: body, query: { includeId: true } }
+
+    self.class.post("/v1/image", options)
+  end
+
+  # Creates an image from a saved template with an API request.
+  #
+  # @see https://docs.htmlcsstoimage.com/getting-started/templates/
+  #
+  # @param template_id [String] the saved template ID
+  # @param template_values [Hash] values to substitute into the template
+  # @param template_version [Integer, nil] a specific template version, or the latest when omitted
+  # @param format [String, nil] the format used in the initially returned URL: `png`, `jpg`, `webp`, or `pdf`; does not change the stored image definition
+  # @param keyword_values [Hash] template values passed as Ruby keyword arguments
+  # @return [HTMLCSSToImage::ApiResponse] image details, including `.url`
+  def create_templated_image(
+    template_id,
+    template_values = {},
+    template_version: nil,
+    format: nil,
+    **keyword_values
+  )
+    template_values = template_values.merge(keyword_values)
+    body = {
+      template_id: template_id,
+      template_values: template_values
+    }
+    body[:template_version] = template_version unless template_version.nil?
+    body[:format] = format unless format.nil?
+
+    self.class.post(
+      "/v1/image",
+      basic_auth: @auth,
+      body: body.to_json,
+      query: { includeId: true }
+    )
+  end
+
+  # Creates several HTML/CSS or URL images in one API request.
+  #
+  # Templates are not supported in batch requests.
+  #
+  # @see https://docs.htmlcsstoimage.com/getting-started/using-the-api
+  #
+  # @param variations [Array<Hash>] per-image values
+  # @param default_options [Hash, nil] shared values inherited by each variation; `format` may be `png`, `jpg`, `webp`, or `pdf` and only changes initially returned URL extensions
+  # @return [HTMLCSSToImage::ApiResponse] batch response with images available at `.images`
+  def create_image_batch(variations, default_options = nil)
+    return ApiResponse.new(images: []) if variations.empty?
+
+    body = { variations: variations }
+    body[:default_options] = default_options unless default_options.nil?
+
+    self.class.post(
+      "/v1/image/batch",
+      basic_auth: @auth,
+      body: body.to_json
+    )
+  end
+
+  # Deletes an image.
+  #
+  # @see https://docs.htmlcsstoimage.com/getting-started/using-the-api
+  #
+  # @param image_id [String] the ID of the image to delete
+  # @return [Boolean, HTMLCSSToImage::ApiResponse] true on success, or the API response on failure
+  def delete_image(image_id)
+    response = self.class.delete("/v1/image/#{image_id}", basic_auth: @auth)
+
+    return true if response.success?
+
+    response
+  end
+
+  # Deletes multiple images in one request.
+  #
+  # @see https://docs.htmlcsstoimage.com/getting-started/using-the-api
+  #
+  # @param image_ids [Array<String>] IDs of the images to delete
+  # @return [Boolean, HTMLCSSToImage::ApiResponse] true on success, or the API response on failure
+  def delete_image_batch(image_ids)
+    return true if image_ids.empty?
+
+    response = self.class.delete(
+      "/v1/image/batch",
+      basic_auth: @auth,
+      body: { ids: image_ids }.to_json
+    )
+
+    return true if response.success?
+
+    response
+  end
+end

data/lib/htmlcsstoimage/signed_urls.rb

@@ -0,0 +1,130 @@
+class HTMLCSSToImage
+  # Generates a signed URL for rendering an image from a saved template.
+  #
+  # This method makes no network requests. Hashes and arrays in
+  # `template_values` are encoded as JSON before the query string is signed.
+  #
+  # @see https://docs.htmlcsstoimage.com/getting-started/create-and-render/
+  #
+  # @param template_id [String] the saved template ID
+  # @param template_values [Hash] values to substitute into the template
+  # @param template_version [Integer, nil] a specific template version, or the latest when omitted
+  # @param format [String, nil] output format appended to the signed URL path: `png`, `jpg`, `webp`, or `pdf`
+  # @param keyword_values [Hash] template values passed as Ruby keyword arguments
+  # @return [HTMLCSSToImage::ApiResponse] signed URL available at `.url`
+  def generate_templated_image_url(
+    template_id,
+    template_values = {},
+    template_version: nil,
+    format: nil,
+    **keyword_values
+  )
+    template_values = template_values.merge(keyword_values)
+    pairs = []
+    pairs << ["template_version", template_version.to_s] unless template_version.nil?
+
+    template_values.sort_by { |key, _value| key.to_s }.each do |key, value|
+      next if value.nil?
+
+      pairs << [key.to_s, signed_value(value)]
+    end
+
+    query = Addressable::URI.form_encode(pairs)
+    token = generate_hmac_token(query)
+    separator = query.empty? ? "" : "?"
+    format_path = format.nil? ? "" : "/#{format}"
+
+    ApiResponse.new(
+      url: "https://hcti.io/v1/image/#{template_id}/#{token}#{format_path}#{separator}#{query}"
+    )
+  end
+
+  # Compatibility proxy for {#generate_templated_image_url}.
+  #
+  # The third positional hash was accepted by previous versions but was not
+  # used. Its `template_version` value is now honored when present.
+  #
+  # @deprecated Use {#generate_templated_image_url} instead.
+  # @param template_id [String] the saved template ID
+  # @param template_values [Hash] values to substitute into the template
+  # @param params [Hash] legacy options; only `template_version` is used
+  # @param template_version [Integer, nil] a specific template version
+  # @param format [String, nil] output format appended to the signed URL path: `png`, `jpg`, `webp`, or `pdf`
+  # @param keyword_values [Hash] template values passed as Ruby keyword arguments
+  # @return [HTMLCSSToImage::ApiResponse] signed URL available at `.url`
+  def create_image_from_template(
+    template_id,
+    template_values = {},
+    params = {},
+    template_version: nil,
+    format: nil,
+    **keyword_values
+  )
+    params ||= {}
+    template_values = template_values.merge(keyword_values)
+    legacy_version =
+      if params.is_a?(Hash)
+        params[:template_version] || params["template_version"]
+      end
+
+    options = { template_version: template_version || legacy_version }
+    options[:format] = format unless format.nil?
+
+    generate_templated_image_url(template_id, template_values, **options)
+  end
+
+  # Generates a signed create-and-render URL for a URL screenshot.
+  #
+  # This method makes no network requests. PDF options are omitted because the
+  # create-and-render endpoint does not support them. `dedupe_duration_s` is
+  # omitted because deduplication applies only to standard POST requests. False
+  # boolean values are omitted except for `transparent_background`, where both
+  # values are meaningful.
+  #
+  # @see https://docs.htmlcsstoimage.com/getting-started/create-and-render/
+  #
+  # @param url [String] the fully qualified URL to capture
+  # @param params [Hash] URL screenshot options; `format` may be `png`, `jpg`, `webp`, or `pdf` and is appended to the signed URL path instead of the query string
+  # @return [HTMLCSSToImage::ApiResponse] signed URL available at `.url`
+  def generate_create_and_render_url(url, params = {})
+    pairs = [["url", url.to_s]]
+    format = params[:format] || params["format"]
+
+    params
+      .reject do |key, _value|
+        %w[url format pdf_options dedupe_duration_s].include?(key.to_s)
+      end
+      .sort_by { |key, _value| key.to_s }
+      .each do |key, value|
+        next if value.nil?
+        next if value == false && key.to_s != "transparent_background"
+
+        case key.to_s
+        when "headers"
+          value.each { |name, header_value| pairs << ["headers", "#{name}:#{header_value}"] }
+        when "additional_header_origins"
+          value.each { |origin| pairs << ["additional_header_origins", origin.to_s] }
+        else
+          pairs << [key.to_s, signed_value(value)]
+        end
+      end
+
+    query = Addressable::URI.form_encode(pairs)
+    token = generate_hmac_token(query)
+    format_path = format.nil? ? "" : "/#{format}"
+
+    ApiResponse.new(
+      url: "https://hcti.io/v1/image/create-and-render/#{@auth[:username]}/#{token}#{format_path}?#{query}"
+    )
+  end
+
+  private
+
+  def generate_hmac_token(query)
+    OpenSSL::HMAC.hexdigest("sha256", @auth[:password], query)
+  end
+
+  def signed_value(value)
+    value.is_a?(Array) || value.is_a?(Hash) ? JSON.generate(value) : value.to_s
+  end
+end