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

Defined Under Namespace

Classes: TimeoutClassifier

Constant Summary collapse

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

Video renders legitimately run minutes; these per-call defaults override the global timeout for the video endpoints only.

300
DEFAULT_VIDEO_TEMPLATE_TIMEOUT = 
180

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:



37
38
39
40
41
42
43
44
 
# File 'lib/pictify/client.rb', line 37

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:



283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/pictify/client.rb', line 283

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

#create_video_template(name:, tsx:, width: 1080, height: 1080, fps: 30, duration_seconds: 8, timeout: nil) ⇒ VideoTemplate

Upload a Remotion scene you wrote as a new video template.

POST /video/templates — unwraps the { template } envelope. The SDK sends kind: "tsx", status: "draft" and computes durationInFrames = (duration_seconds * fps).round.

The source passes a compile gate BEFORE anything is saved: invalid tsx rejects with a 422 RenderError carrying the compiler errors (+error.errors+) and creates NOTHING, so retrying cannot litter the account with broken templates.

Parameters:

  • name (String) —

    Template name shown in the dashboard

  • tsx (String) —

    The complete single-file Remotion scene source. Must export a zod schema (flat fields with defaults — they become the template's variables) and a default React component; imports limited to remotion, react and zod

  • width (Integer) (defaults to: 1080) —

    Canvas width in pixels (default 1080)

  • height (Integer) (defaults to: 1080) —

    Canvas height in pixels (default 1080)

  • fps (Integer) (defaults to: 30) —

    Frames per second (default 30)

  • duration_seconds (Numeric) (defaults to: 8) —

    Video length in seconds (default 8)

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

    Per-call timeout in seconds (default 180 — the compile gate bundles the scene)

Returns:



400
401
402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/pictify/client.rb', line 400

def create_video_template(name:, tsx:, width: 1080, height: 1080, fps: 30,
                          duration_seconds: 8, timeout: nil)
  response = request(:post, "video/templates", {
    name: name,
    kind: "tsx",
    tsx: tsx,
    width: width,
    height: height,
    fps: fps,
    durationInFrames: (duration_seconds * fps).round,
    status: "draft"
  }, nil, timeout: timeout || DEFAULT_VIDEO_TEMPLATE_TIMEOUT)
  VideoTemplate.new(response["template"] || {})
end

#generate_video_template(prompt:, width: 1080, height: 1080, duration_seconds: 8, brand_color: nil, timeout: nil) ⇒ GenerateVideoTemplateResult

Generate a new video template from a prompt using AI.

POST /video/templates/generate — the service designs a motion brief, writes the scene as code, compiles it, renders preview frames and reviews them visually — then saves a draft template whose texts, colors and optional image are editable variables. Takes 30-60 seconds; metered as one render.

Parameters:

  • prompt (String) —

    What the video is for, with any mood/style guidance (max 2000 chars)

  • width (Integer) (defaults to: 1080) —

    Canvas width in pixels (default 1080)

  • height (Integer) (defaults to: 1080) —

    Canvas height in pixels (default 1080)

  • duration_seconds (Numeric) (defaults to: 8) —

    Video length in seconds, 1-60 (default 8)

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

    Optional brand color (hex) to build the palette around

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

    Per-call timeout in seconds (default 180)

Returns:



365
366
367
368
369
370
371
372
373
374
375
 
# File 'lib/pictify/client.rb', line 365

def generate_video_template(prompt:, width: 1080, height: 1080, duration_seconds: 8,
                            brand_color: nil, timeout: nil)
  response = request(:post, "video/templates/generate", {
    prompt: prompt,
    width: width,
    height: height,
    durationSeconds: duration_seconds,
    brandColor: brand_color
  }, nil, timeout: timeout || DEFAULT_VIDEO_TEMPLATE_TIMEOUT)
  GenerateVideoTemplateResult.new(response)
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:



231
232
233
234
 
# File 'lib/pictify/client.rb', line 231

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:



246
247
248
249
 
# File 'lib/pictify/client.rb', line 246

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

#get_video_template_variables(template_id) ⇒ VideoTemplateVariables

A video template's variable definitions — what you can set when rendering it. Call before #render_video to know what to pass.

GET /video/templates/:uid/variables.

Parameters:

  • template_id (String) —

    The video template UID

Returns:



317
318
319
320
 
# File 'lib/pictify/client.rb', line 317

def get_video_template_variables(template_id)
  response = request(:get, "video/templates/#{encode(template_id)}/variables")
  VideoTemplateVariables.new(response)
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:



260
261
262
263
264
265
266
267
268
 
# File 'lib/pictify/client.rb', line 260

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

#list_video_templates ⇒ Array<VideoTemplate>

List your video templates.

GET /video/templates — unwraps the { templates } envelope.

Returns:



305
306
307
308
 
# File 'lib/pictify/client.rb', line 305

def list_video_templates
  response = request(:get, "video/templates")
  (response["templates"] || []).map { |t| VideoTemplate.new(t) }
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:



117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/pictify/client.rb', line 117

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:



211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/pictify/client.rb', line 211

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:



176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/pictify/client.rb', line 176

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