Ruby SDK

Install the orshot gem, then call render_from_template with a template ID and modifications.

Updated Oct 27, 2026

Installation#

Add this line to your application's Gemfile:

Ruby

gem 'orshot'

And then execute:

Shell

bundle install

Or install it yourself as:

Shell

gem install orshot

Initialise#

Ruby

require 'orshot'

client = Orshot::Client.new('YOUR_ORSHOT_API_KEY')

render_from_studio_template#

Render from a custom Studio template. Supports image, PDF, video generation and publishing to social accounts.

Generate Image#

Ruby

response = client.render_from_studio_template({
  'template_id' => 1234,
  'modifications' => {
    'title' => 'Orshot Studio',
    'description' => 'Generate images from custom templates',
  },
  'response' => { 'type' => 'url', 'format' => 'png', 'scale' => 2 },
})

JavaScript

{
  "data": {
    "content": "https://storage.orshot.com/.../image.png",
    "format": "png",
    "type": "url",
    "responseTime": 3550.43
  }
}

Generate PDF#

Ruby

response = client.render_from_studio_template({
  'template_id' => 1234,
  'modifications' => { 'title' => 'Invoice #1234' },
  'response' => { 'type' => 'url', 'format' => 'pdf' },
  'pdf_options' => {
    'margin' => '20px',
    'range_from' => 1,
    'range_to' => 2,
    'color_mode' => 'rgb',
    'dpi' => 300,
  },
})

Generate Video#

Ruby

response = client.render_from_studio_template({
  'template_id' => 1234,
  'modifications' => {
    'videoElement' => 'https://example.com/custom-video.mp4',
    'videoElement.trimStart' => 0,
    'videoElement.trimEnd' => 10,
  },
  'response' => { 'type' => 'url', 'format' => 'mp4' },
  'video_options' => {
    'trim_start' => 0,
    'trim_end' => 20,
    'muted' => false,
    'loop' => true,
  },
})

Ruby

response = client.render_from_studio_template({
  'template_id' => 1234,
  'modifications' => { 'title' => 'Check out our latest update!' },
  'response' => { 'type' => 'url', 'format' => 'png' },
  'publish' => {
    'accounts' => [1, 2],
    'content' => 'Check out our latest design!',
  },
})
# response['publish'] => [{ 'platform' => 'twitter', 'username' => 'acmehq', 'status' => 'published' }, ...]

Schedule a Post#

Ruby

response = client.render_from_studio_template({
  'template_id' => 1234,
  'modifications' => { 'title' => 'Scheduled post' },
  'response' => { 'type' => 'url', 'format' => 'png' },
  'publish' => {
    'accounts' => [1],
    'content' => 'This will be posted later!',
    'schedule' => { 'scheduled_for' => '2026-04-01T10:00:00Z' },
    'timezone' => 'America/New_York',
  },
})

Parameters#

key	required	description
`template_id`	Yes	ID of the Studio template.
`modifications`	No	Hash of dynamic modifications for the template.
`response.type`	No	`base64`, `binary`, `url` (Defaults to `url`).
`response.format`	No	`png`, `webp`, `jpg`, `jpeg`, `avif`, `pdf`, `mp4`, `webm`, `mov`, `mkv`, `gif` (Defaults to `png`).
`response.scale`	No	Scale of the output (`1` = original, `2` = double). Defaults to `1`.
`response.include_pages`	No	Page numbers to render for multi-page templates (e.g. `[1, 3]`).
`response.file_name`	No	Custom file name (without extension). Works with `url` and `binary` types.
`pdf_options.margin`	No	CSS margin value (e.g. `"20px"`).
`pdf_options.range_from`	No	Start page number for PDF output.
`pdf_options.range_to`	No	End page number for PDF output.
`pdf_options.color_mode`	No	`rgb` or `cmyk`.
`pdf_options.dpi`	No	DPI for print quality (e.g. `300`).
`video_options.trim_start`	No	Trim start time in seconds.
`video_options.trim_end`	No	Trim end time in seconds.
`video_options.muted`	No	Mute audio track.
`video_options.loop`	No	Loop the video.
`publish.accounts`	Yes, when `publish` is set	Array of social account IDs from your workspace.
`publish.content`	No	Caption/text for the social post.
`publish.is_draft`	No	`true` to save as draft instead of publishing.
`publish.schedule.scheduled_for`	No	ISO date string to schedule the post.
`publish.timezone`	No	Timezone string (e.g. `"America/New_York"`).
`publish.platform_options`	No	Per-account options keyed by account ID.

render_from_template#

Render from a pre-built Orshot template.

Ruby

response = client.render_from_template({
  'template_id' => 'open-graph-image-1',
  'modifications' => {
    'title' => 'Orshot',
    'description' => 'Create Visuals and Automate Image Generation',
  },
  'response_type' => 'url',
  'response_format' => 'png',
})

JavaScript

{
  "data": {
    "content": "https://storage.orshot.com/.../image.png",
    "format": "png",
    "type": "url",
    "responseTime": 3550.43
  }
}

key	required	description
`template_id`	Yes	ID of the template (`open-graph-image-1`, `tweet-image`, `beautify-screenshot`, ...)
`modifications`	Yes	Modifications for the selected template.
`response_type`	No	`base64`, `binary`, `url` (Defaults to `url`).
`response_format`	No	`png`, `webp`, `pdf`, `jpg`, `jpeg`, `avif` (Defaults to `png`).

With response_type set to url or base64, read the result like a hash, for example response['data']['content'].

For available templates and their modifications refer Orshot Templates Page

generate_signed_url#

Generate a signed URL for a library template. Opening the URL renders the image.

Ruby

response = client.generate_signed_url({
  'template_id' => 'open-graph-image-1',
  'modifications' => { 'title' => 'Hello World' },
  'expires_at' => 1744276943,
})

JavaScript

{
  "data": {
    "url": "https://api.orshot.com/v1/generate/images?templateId=open-graph-image-1&expiresAt=1744276943&..."
  }
}

key	required	description
`template_id`	Yes	ID of the template (`open-graph-image-1`, `tweet-image`, `beautify-screenshot`, ...)
`modifications`	Yes	Modifications for the selected template.
`expires_at`	Yes	Unix timestamp in seconds, or `"never"` for a URL that does not expire.
`render_type`	No	Only `images` works. Leave it out to use `images`.

The URL renders a PNG by default. To get another format, add responseFormat inside modifications, for example 'modifications' => { 'title' => 'Hello World', 'responseFormat' => 'jpg' }.

Error Handling#

A failed request raises Orshot::Error with the API's error text.

Ruby

begin
  response = client.render_from_studio_template({
    'template_id' => 1234,
    'modifications' => { 'title' => 'Hello' },
  })
rescue Orshot::Error => e
  puts e.message
end