Ruby SDK

The official Ruby gem for the cloudlayer.io document generation platform. Convert HTML, URLs, and templates to PDF and images, manage jobs, assets, and storage configurations.

RubyGems · GitHub Source

Installation

Add to your Gemfile:

gem "cloudlayerio", "~> 0.1"

Then run:

bundle install

Or install directly:

gem install cloudlayerio

Setup

require "cloudlayerio"

client = CloudLayerio::Client.new(
  api_key: "your-api-key",
  api_version: :v2
)

Get your API key from the cloudlayer.io dashboard.

API Versions:

:v1 — synchronous, returns binary PDF/image data directly
:v2 — asynchronous, returns a Job object (poll for completion, then download)

URL to PDF

# v2 (async)
result = client.url_to_pdf(
  url: "https://example.com",
  format: "a4",
  print_background: true,
  async: true,
  storage: true
)

job = client.wait_for_job(result.job.id)
data = client.download_job_result(job)
File.binwrite("output.pdf", data)

# v1 (sync) — returns binary directly
v1_client = CloudLayerio::Client.new(api_key: "your-key", api_version: :v1)
result = v1_client.url_to_pdf(url: "https://example.com")
File.binwrite("output.pdf", result.bytes)

URL to Image

result = client.url_to_image(
  url: "https://example.com",
  image_type: "png",
  quality: 90
)

HTML to PDF

html = CloudLayerio::Util::HtmlUtil.encode_html(<<~HTML)
  <html>
    <body>
      <h1>Invoice #001</h1>
      <p>Thank you for your purchase.</p>
    </body>
  </html>
HTML

result = client.html_to_pdf(
  html: html,
  format: "letter",
  print_background: true
)

HTML to Image

html = CloudLayerio::Util::HtmlUtil.encode_html("<div style='padding:40px'><h1>Hello</h1></div>")
result = client.html_to_image(html: html, image_type: "png")

Template to PDF

result = client.template_to_pdf(
  template_id: "your-template-id",
  data: {
    company: "Acme Corp",
    invoice_number: "INV-001",
    items: [{ name: "Widget", price: 9.99 }]
  }
)

Template to Image

result = client.template_to_image(
  template_id: "your-template-id",
  data: { title: "Certificate of Completion" },
  image_type: "png"
)

Document Conversion

DOCX to PDF

result = client.docx_to_pdf(file: "/path/to/document.docx")

DOCX to HTML

result = client.docx_to_html(file: "/path/to/document.docx")

PDF to DOCX

result = client.pdf_to_docx(file: "/path/to/document.pdf")

Merge PDFs

result = client.merge_pdfs(
  batch: CloudLayerio::Options::Batch.new(urls: [
    "https://example.com/page1.pdf",
    "https://example.com/page2.pdf"
  ])
)

Data Management

Jobs & Assets

jobs = client.list_jobs          # Up to 10 most recent
job = client.get_job("job-id")

assets = client.list_assets      # Up to 10 most recent
asset = client.get_asset("asset-id")

Account

account = client.get_account
puts "Calls: #{account.calls}/#{account.calls_limit}"

Templates

templates = client.list_templates(type: "pdf", category: "invoice")
template = client.get_template("template-id")

Storage

storages = client.list_storage
detail = client.get_storage("storage-id")

resp = client.add_storage(
  title: "My S3",
  region: "us-east-1",
  access_key_id: "AKIA...",
  secret_access_key: "...",
  bucket: "my-bucket"
)

client.delete_storage("storage-id")

Configuration Options

Option	Type	Default	Description
`api_key`	String	required	Your cloudlayer.io API key
`api_version`	Symbol	required	`:v1` or `:v2`
`base_url`	String	`https://api.cloudlayer.io`	API base URL
`timeout`	Numeric	`30`	Request timeout (seconds)
`max_retries`	Integer	`2`	Retry attempts for 429/5xx (0-5)
`user_agent`	String	`cloudlayerio-ruby/VERSION`	User-Agent header
`headers`	Hash	`{}`	Additional HTTP headers

Error Handling

begin
  result = client.url_to_pdf(url: "https://example.com")
rescue CloudLayerio::AuthError => e
  puts "Auth failed (#{e.status_code}): #{e.message}"
rescue CloudLayerio::RateLimitError => e
  puts "Rate limited, retry after #{e.retry_after}s"
rescue CloudLayerio::ApiError => e
  puts "API error #{e.status_code}: #{e.message}"
rescue CloudLayerio::TimeoutError
  puts "Request timed out"
rescue CloudLayerio::NetworkError
  puts "Connection failed"
rescue CloudLayerio::ValidationError => e
  puts "Invalid input: #{e.message}"
end

Requirements

Ruby >= 3.1
One runtime dependency: base64 gem (bundled in Ruby stdlib; extracted in Ruby 3.4+)