htmlcsstoimage-api 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 939005ab5dbc481066edc4aa72e5b6118dffbf38111245ac81b5a07a5c3e7b62
-  data.tar.gz: 90755ad2b9c749f6e95d90142ce34ed9f9e25c38da546ada1c4d9dbb50552eec
+  metadata.gz: 38df32b2223110a9e3a096a56984fa3f3bb4ec963193c9cf4cea7f078e9026c3
+  data.tar.gz: 28bdef1535be738ebc2ddbbab194f7ac51cd0fc416edb071c623d6efdc320cc8
 SHA512:
-  metadata.gz: 89dd9fd2ae2adaec762cbb41e3453a154764eb9437c32a750d4e0d92e4d25a4dcfe4883f7807b2af23a17a2f9a6fbdc55043853673ea2e231cb78275ea002baf
-  data.tar.gz: 1e7c86833503da5758b89bbf5020951bad4deb031603064d27cedf6abdbe8468db078382eeea53e5994ea62529054a6affe8643160982ba85f4ae70d24658505
+  metadata.gz: 84a023aaaab14f26092d3f6da4d1d41edec173462488287bbbb7a951bf861cfe73590009e8342c5c77fe85cbfb917045d2ebb8833d3d0cb5a263dad2b3369d00
+  data.tar.gz: bf9e8f408a9c622bf5f17c91c45ac4834379e4b354379afe98c6f6ba5eda01e89316ce62fe4203fdcb39ed90ac5840d5b92ebc2d9c36440a126a915580f4be20

data/.github/workflows/ruby.yml

@@ -12,11 +12,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: 2.6
     - name: Install dependencies
       run: bundle install
     - name: Run tests

data/.ruby-version

@@ -1 +1 @@
-3.1.3
+3.3.5

data/Gemfile.lock

@@ -1,56 +1,62 @@
 PATH
   remote: .
   specs:
-    htmlcsstoimage-api (0.1.3)
+    htmlcsstoimage-api (0.3.0)
       addressable (> 2.5.0)
       httparty (> 0.10)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.7.0)
-      public_suffix (>= 2.0.2, < 5.0)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    base64 (0.2.0)
+    bigdecimal (3.1.8)
     byebug (11.1.3)
     coderay (1.1.3)
-    crack (0.4.3)
-      safe_yaml (~> 1.0.0)
-    diff-lcs (1.4.4)
-    hashdiff (1.0.1)
-    httparty (0.18.1)
-      mime-types (~> 3.0)
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    csv (3.3.0)
+    diff-lcs (1.5.1)
+    hashdiff (1.1.1)
+    httparty (0.22.0)
+      csv
+      mini_mime (>= 1.0.0)
       multi_xml (>= 0.5.2)
-    method_source (1.0.0)
-    mime-types (3.3.1)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2021.0212)
-    multi_xml (0.6.0)
-    pry (0.13.1)
+    method_source (1.1.0)
+    mini_mime (1.1.5)
+    multi_xml (0.7.1)
+      bigdecimal (~> 3.1)
+    pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    pry-byebug (3.9.0)
+    pry-byebug (3.10.1)
       byebug (~> 11.0)
-      pry (~> 0.13.0)
-    public_suffix (4.0.5)
-    rake (13.0.1)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.2)
-      rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.2)
+      pry (>= 0.13, < 0.15)
+    public_suffix (6.0.1)
+    rake (13.2.1)
+    rexml (3.3.9)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.2)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.3)
-    safe_yaml (1.0.5)
-    vcr (6.0.0)
-    webmock (3.8.3)
-      addressable (>= 2.3.6)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    vcr (6.3.1)
+      base64
+    webmock (3.24.0)
+      addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.45)
 
 PLATFORMS
   ruby
@@ -64,6 +70,7 @@ DEPENDENCIES
   rspec (~> 3.0)
   vcr
   webmock
+  yard (~> 0.9)
 
 BUNDLED WITH
-   2.1.4
+   2.5.23

data/README.md

@@ -4,14 +4,14 @@
 
 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
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'htmlcsstoimage-api'
+gem 'htmlcsstoimage-api', require: 'htmlcsstoimage'
 ```
 
 And then execute:
@@ -27,6 +27,7 @@ Or install it yourself as:
 Create a new instance of 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")
 ```
@@ -36,16 +37,19 @@ 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
+require "htmlcsstoimage"
 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">
@@ -54,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
@@ -75,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.
@@ -100,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