Class: Pictify::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/pictify/client.rb

Overview

Client for the Pictify API.

Generate images, PDFs, and GIFs from raw HTML, live URLs, and reusable templates.

Examples:

Render raw HTML to a PNG

client = Pictify::Client.new(api_key: "your-api-key")
image = client.render_html(html: "<div>Hello World</div>", width: 1200, height: 630)
puts image.url

Render a template

result = client.render(template_id: "your-template-uid", variables: { name: "Ada" })
puts result.url # results.first.url

Constant Summary collapse

DEFAULT_BASE_URL = 
"https://api.pictify.io"
DEFAULT_TIMEOUT = 
30
DEFAULT_MAX_RETRIES = 
3

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String) —

    Your Pictify API key

  • base_url (String) (defaults to: DEFAULT_BASE_URL) —

    Custom API base URL

  • timeout (Integer) (defaults to: DEFAULT_TIMEOUT) —

    Request timeout in seconds

  • max_retries (Integer) (defaults to: DEFAULT_MAX_RETRIES) —

    Maximum retry attempts (5xx / network only)

Raises:



32
33
34
35
36
37
38
39
 
# File 'lib/pictify/client.rb', line 32

def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
  raise AuthenticationError, "API key is required" if api_key.nil? || api_key.empty?

  @api_key = api_key
  @base_url = base_url.chomp("/")
  @timeout = timeout
  @max_retries = max_retries
end

Instance Method Details

#create_template(html:, name: nil, width: nil, height: nil, variable_definitions: nil, output_format: nil) ⇒ Template

Create a template from HTML.

POST /templates — unwraps the { template } envelope. Variables are auto-discovered from {{variableName}} tokens in the HTML body.

Parameters:

  • html (String) —

    Raw HTML body

  • name (String, nil) (defaults to: nil) —

    Template name

  • width (Integer, nil) (defaults to: nil) —

    Default width in pixels

  • height (Integer, nil) (defaults to: nil) —

    Default height in pixels

  • variable_definitions (Array<Hash>, nil) (defaults to: nil) —

    Explicit variable definitions (auto-extracted from HTML when omitted)

  • output_format (Symbol, String, nil) (defaults to: nil) —

    Output format (“image” | “pdf”, default image)

Returns:



278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/pictify/client.rb', line 278

def create_template(html:, name: nil, width: nil, height: nil, variable_definitions: nil,
                    output_format: nil)
  response = request(:post, "templates", {
    html: html,
    name: name,
    width: width,
    height: height,
    variableDefinitions: variable_definitions,
    outputFormat: output_format.nil? ? nil : output_format.to_s
  })
  Template.new(response["template"] || {})
end

#get_batch_results(batch_id) ⇒ BatchResults

Get the status, progress, and per-item results of a batch job.

GET /templates/batch/:batch_id/results. Results carry index, success, and variables (plus error on failures) but NOT rendered URLs.

Parameters:

  • batch_id (String) —

    The batch job ID returned by #render_batch

Returns:



226
227
228
229
 
# File 'lib/pictify/client.rb', line 226

def get_batch_results(batch_id)
  response = request(:get, "templates/batch/#{encode(batch_id)}/results")
  BatchResults.new(response)
end

#get_template(template_id) ⇒ Template

Get a single template by its UID.

GET /templates/:uid — unwraps the { template } envelope.

Parameters:

  • template_id (String) —

    The template UID

Returns:



241
242
243
244
 
# File 'lib/pictify/client.rb', line 241

def get_template(template_id)
  response = request(:get, "templates/#{encode(template_id)}")
  Template.new(response["template"] || {})
end

#list_templates(page: nil, limit: nil, sort: nil) ⇒ ListTemplatesResult

List templates in your account.

GET /templates — returns a ListTemplatesResult with templates and pagination.

Parameters:

  • page (Integer, nil) (defaults to: nil) —

    Page number (1-based, default 1)

  • limit (Integer, nil) (defaults to: nil) —

    Items per page (max 100, default 12)

  • sort (Symbol, String, nil) (defaults to: nil) —

    Sort order (:newest, :oldest, :name)

Returns:



255
256
257
258
259
260
261
262
263
 
# File 'lib/pictify/client.rb', line 255

def list_templates(page: nil, limit: nil, sort: nil)
  params = {}
  params[:page] = page unless page.nil?
  params[:limit] = limit unless limit.nil?
  params[:sort] = sort.to_s unless sort.nil?

  response = request(:get, "templates", nil, params)
  ListTemplatesResult.new(response)
end

#render(template_id:, variables: {}, format: nil, quality: nil, width: nil, height: nil, layout: nil, layouts: nil) ⇒ RenderResult

Render a single image (or PDF) from a template.

POST /templates/:uid/render — returns the RenderResult results envelope, with a convenience url accessor (results.first.url).

Parameters:

  • template_id (String) —

    The UID of the template to render

  • variables (Hash) (defaults to: {}) —

    Variables to inject into the template

  • format (Symbol, String, nil) (defaults to: nil) —

    Output format (default png; pdf supported)

  • quality (Float, nil) (defaults to: nil) —

    Render quality for raster output (0.1–1.0, default 0.9)

  • width (Integer, nil) (defaults to: nil) —

    Output width in pixels

  • height (Integer, nil) (defaults to: nil) —

    Output height in pixels

  • layout (String, nil) (defaults to: nil) —

    Render a single named layout variant

  • layouts (Array<String>, nil) (defaults to: nil) —

    Render multiple named layout variants (max 20)

Returns:



112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/pictify/client.rb', line 112

def render(template_id:, variables: {}, format: nil, quality: nil, width: nil, height: nil,
           layout: nil, layouts: nil)
  response = request(:post, "templates/#{encode(template_id)}/render", {
    variables: variables || {},
    format: (format || :png).to_s,
    quality: quality,
    width: width,
    height: height,
    layout: layout,
    layouts: layouts
  })
  RenderResult.new(response)
end

#render_batch(template_id:, variable_sets:, format: nil, quality: nil, concurrency: nil, layout: nil, layouts: nil) ⇒ BatchRenderResult

Submit an async batch render of a template across many variable sets.

POST /templates/:uid/batch-render — returns a BatchRenderResult with batch_id, status, total_items immediately (HTTP 202). Poll #get_batch_results to track progress.

Rendered URLs are NOT returned by the poll endpoint — they are delivered via the render.completed webhook.

Parameters:

  • template_id (String) —

    The UID of the template to render

  • variable_sets (Array<Hash>) —

    Variable sets — one render per set (max 100)

  • format (Symbol, String, nil) (defaults to: nil) —

    Output format (default png)

  • quality (Float, nil) (defaults to: nil) —

    Render quality for raster output (0.1–1.0, default 0.9)

  • concurrency (Integer, nil) (defaults to: nil) —

    Maximum parallel renders (1–10, default 5)

  • layout (String, nil) (defaults to: nil) —

    Render a single named layout variant for every item

  • layouts (Array<String>, nil) (defaults to: nil) —

    Render multiple named layout variants for every item

Returns:



206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/pictify/client.rb', line 206

def render_batch(template_id:, variable_sets:, format: nil, quality: nil, concurrency: nil,
                 layout: nil, layouts: nil)
  response = request(:post, "templates/#{encode(template_id)}/batch-render", {
    variableSets: variable_sets,
    format: (format || :png).to_s,
    quality: quality,
    concurrency: concurrency,
    layout: layout,
    layouts: layouts
  })
  BatchRenderResult.new(response)
end

#render_gif(html: nil, url: nil, template_id: nil, variables: nil, width: nil, height: nil, quality: nil) ⇒ GifRenderResult

Render an animated GIF from raw HTML, a live URL, or a template.

POST /gif — the { gif: {…} } envelope is flattened to a GifRenderResult (url, uid, width, height, animation_length). Provide exactly one source: html, url, or template_id.

Parameters:

  • html (String, nil) (defaults to: nil) —

    Raw HTML to render into a GIF (must contain motion)

  • url (String, nil) (defaults to: nil) —

    A live URL to capture motion from

  • template_id (String, nil) (defaults to: nil) —

    A template UID to render into a GIF

  • variables (Hash, nil) (defaults to: nil) —

    Variables to inject when using template_id

  • width (Integer, nil) (defaults to: nil) —

    Output width in pixels (default 800)

  • height (Integer, nil) (defaults to: nil) —

    Output height in pixels (default 600)

  • quality (Symbol, String, nil) (defaults to: nil) —

    Quality preset (:low, :medium, :high; default medium)

Returns:



171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/pictify/client.rb', line 171

def render_gif(html: nil, url: nil, template_id: nil, variables: nil, width: nil, height: nil,
               quality: nil)
  response = request(:post, "gif", {
    html: html,
    url: url,
    template: template_id,
    variables: variables,
    width: width,
    height: height,
    quality: (quality || :medium).to_s
  })
  GifRenderResult.new(response["gif"] || {})
end

#render_html(html:, css: nil, width: nil, height: nil, selector: nil, format: nil) ⇒ ImageResult

Render an image (or PDF) directly from HTML.

POST /image — returns an ImageResult with url, id, created_at.

Parameters:

  • html (String) —

    Raw HTML content to render

  • css (String, nil) (defaults to: nil) —

    Optional CSS, injected into the HTML inside a <style> tag before rendering (the /image endpoint takes a single html field)

  • width (Integer, nil) (defaults to: nil) —

    Output width in pixels (default 1280)

  • height (Integer, nil) (defaults to: nil) —

    Output height in pixels (default 720)

  • selector (String, nil) (defaults to: nil) —

    CSS selector to crop the screenshot to

  • format (Symbol, String, nil) (defaults to: nil) —

    Output format, mapped to fileExtension (default png)

Returns:



59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/pictify/client.rb', line 59

def render_html(html:, css: nil, width: nil, height: nil, selector: nil, format: nil)
  body = css ? "<style>#{css}</style>#{html}" : html

  response = request(:post, "image", {
    html: body,
    width: width,
    height: height,
    selector: selector,
    fileExtension: (format || :png).to_s
  })
  ImageResult.new(response)
end

#render_layouts(template_id:, layouts:, variables: {}, format: nil, quality: nil, width: nil, height: nil) ⇒ RenderResult

Render multiple layout variants of a template in a single call.

POST /templates/:uid/render with layouts — returns one results item per successful layout; missing/invalid layouts appear in errors.

Parameters:

  • template_id (String) —

    The UID of the template to render

  • layouts (Array<String>) —

    Layout variant names to render (max 20). Use “default” for the base layout.

  • variables (Hash) (defaults to: {}) —

    Variables to inject into the template

  • format (Symbol, String, nil) (defaults to: nil) —

    Output format (default png)

  • quality (Float, nil) (defaults to: nil) —

    Render quality for raster output (0.1–1.0)

  • width (Integer, nil) (defaults to: nil) —

    Output width in pixels

  • height (Integer, nil) (defaults to: nil) —

    Output height in pixels

Returns:



140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/pictify/client.rb', line 140

def render_layouts(template_id:, layouts:, variables: {}, format: nil, quality: nil,
                   width: nil, height: nil)
  render(
    template_id: template_id,
    variables: variables,
    format: format,
    quality: quality,
    width: width,
    height: height,
    layouts: layouts
  )
end

#render_url(url:, width: nil, height: nil, selector: nil, format: nil) ⇒ ImageResult

Screenshot a live URL.

POST /image with url — returns an ImageResult.

Parameters:

  • url (String) —

    The URL to screenshot

  • width (Integer, nil) (defaults to: nil) —

    Output width in pixels (default 1280)

  • height (Integer, nil) (defaults to: nil) —

    Output height in pixels (default 720)

  • selector (String, nil) (defaults to: nil) —

    CSS selector to crop the screenshot to

  • format (Symbol, String, nil) (defaults to: nil) —

    Output format, mapped to fileExtension (default png)

Returns:



83
84
85
86
87
88
89
90
91
92
 
# File 'lib/pictify/client.rb', line 83

def render_url(url:, width: nil, height: nil, selector: nil, format: nil)
  response = request(:post, "image", {
    url: url,
    width: width,
    height: height,
    selector: selector,
    fileExtension: (format || :png).to_s
  })
  ImageResult.new(response)
end