Node.js

Get started with Orshot Node SDK

Installation#

npm install --save orshot

yarn add orshot

pnpm install orshot

Import#

import { Orshot } from "orshot";

Initialise#

const orshot = new Orshot(<ORSHOT_API_KEY>);

renderFromStudioTemplate#

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

Generate Image#

const response = await orshot.renderFromStudioTemplate({
  templateId: 1234,
  modifications: {
    title: "Orshot Studio",
    description: "Generate images from custom templates",
  },
  response: { type: "url", format: "png", scale: 2 },
});

Generate PDF#

const response = await orshot.renderFromStudioTemplate({
  templateId: 1234,
  modifications: { title: "Invoice #1234" },
  response: { type: "url", format: "pdf" },
  pdfOptions: {
    margin: "20px",
    rangeFrom: 1,
    rangeTo: 2,
    colorMode: "rgb",
    dpi: 300,
  },
});

Generate Video#

const response = await orshot.renderFromStudioTemplate({
  templateId: 1234,
  modifications: {
    videoElement: "https://example.com/custom-video.mp4",
    "videoElement.trimStart": 0,
    "videoElement.trimEnd": 10,
  },
  response: { type: "url", format: "mp4" },
  videoOptions: {
    trimStart: 0,
    trimEnd: 20,
    muted: false,
    loop: true,
    fps: 30,
    audioSource: "https://example.com/audio.mp3",
  },
});

Multi-page Video with Transitions#

const response = await orshot.renderFromStudioTemplate({
  templateId: 1234,
  response: { type: "url", format: "mp4" },
  videoOptions: {
    combinePages: true,
    pageTransition: "fade",
    pageTransitionDuration: 0.5,
  },
});

const response = await orshot.renderFromStudioTemplate({
  templateId: 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#

const response = await orshot.renderFromStudioTemplate({
  templateId: 1234,
  modifications: { title: "Scheduled post" },
  response: { type: "url", format: "png" },
  publish: {
    accounts: [1],
    content: "This will be posted later!",
    schedule: { scheduledFor: "2026-04-01T10:00:00Z" },
    timezone: "America/New_York",
  },
});

Parameters#

key	required	description
`templateId`	Yes	ID of the Studio template.
`modifications`	No	Object 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.quality`	No	Output quality (`1`-`100`). Controls compression for the rendered output.
`response.includePages`	No	Page numbers to render for multi-page templates (e.g. `[1, 3]`).
`response.fileName`	No	Custom file name (without extension). Works with `url` and `binary` types.
`pdfOptions.margin`	No	CSS margin value (e.g. `"20px"`).
`pdfOptions.rangeFrom`	No	Start page number for PDF output.
`pdfOptions.rangeTo`	No	End page number for PDF output.
`pdfOptions.colorMode`	No	`rgb` or `cmyk`.
`pdfOptions.dpi`	No	DPI for print quality (e.g. `300`).
`videoOptions.trimStart`	No	Trim start time in seconds.
`videoOptions.trimEnd`	No	Trim end time in seconds.
`videoOptions.muted`	No	Mute audio track.
`videoOptions.loop`	No	Loop the video.
`videoOptions.duration`	No	Total video duration in seconds.
`videoOptions.fps`	No	Frames per second (`1`-`30`).
`videoOptions.quality`	No	Video quality (`1`-`100`).
`videoOptions.audioSource`	No	External audio URL or array of per-page audio sources.
`videoOptions.subtitleSource`	No	Subtitle file URL.
`videoOptions.combinePages`	No	Combine multi-page templates into a single video.
`videoOptions.pageTransition`	No	Transition effect between pages (e.g. `"fade"`, `"dissolve"`, `"wipe"`, `"slide"`).
`videoOptions.pageTransitionDuration`	No	Transition duration in seconds (`0.1`-`2`).
`publish.accounts`	No	Array of social account IDs from your workspace.
`publish.content`	No	Caption/text for the social post.
`publish.isDraft`	No	`true` to save as draft instead of publishing.
`publish.schedule.scheduledFor`	No	ISO date string to schedule the post.
`publish.timezone`	No	Timezone string (e.g. `"America/New_York"`).
`publish.platformOptions`	No	Per-account options keyed by account ID.

renderFromTemplate#

Render from a pre-built Orshot template.

const response = await orshot.renderFromTemplate({
  templateId: "open-graph-image-1",
  modifications: {
    title: "Orshot",
    description: "Create Visuals and Automate Image Generation",
  },
  responseType: "url",
  responseFormat: "png",
});

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

For available templates and their modifications refer Orshot Templates Page

generateSignedUrl#

Generate a signed URL for a template.

const response = await orshot.generateSignedUrl({
  templateId: "open-graph-image-1",
  modifications: { title: "Hello World" },
  expiresAt: 1744276943,
  renderType: "images",
  responseFormat: "png",
});

Use "never" for expiresAt to create a non-expiring signed URL.

key	required	description
`templateId`	Yes	ID of the template.
`modifications`	Yes	Modifications for the selected template.
`expiresAt`	Yes	Unix timestamp (number) or `"never"` for no expiration.
`renderType`	No	`images`, `pdfs`, `videos` (Defaults to `images`).
`responseFormat`	No	`png`, `webp`, `pdf`, `jpg`, `jpeg`, `avif` (Defaults to `png`).

Error Handling#

The SDK throws errors with descriptive messages from the API when a request fails.

try {
  const response = await orshot.renderFromStudioTemplate({
    templateId: 1234,
    modifications: { title: "Hello" },
  });
} catch (error) {
  console.error(error.message);
  // e.g. "Template not found in workspace"
  // e.g. "Subscription inactive"
  // e.g. "Invalid API Key"
}

TypeScript#

All types are exported from the package:

import { Orshot } from "orshot";
import type { StudioRenderOptions, VideoOptions, PdfOptions, PublishOptions } from "orshot";

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key

Image, PDF and video generation via API
Visual editor with AI and smart layouts
Zapier, Make, MCP and 50+ integrations
White-label embed for your own app
30 free credits — no credit card required