Render API Reference

How Rendering Works#

1. You send a render request with a template identifier and layer overrides
2. RenderStack loads the template and its elements
3. Dynamic layers are updated with your provided data
4. The image is rendered server-side using the template's canvas configuration
5. The rendered output is returned as a PNG, JPEG, or PDF file

Render Formats#

Format	Description	Best For
PNG	Lossless format with transparency support	Graphics, logos, social cards
JPEG	Compressed format, smaller file size	Photos, complex images
PDF	Portable document format, single or multi-page	Certificates, reports, print-ready media

Note: PDF output embeds the rendered image as a raster graphic inside a PDF document. Text is not selectable — it is rasterized just like PNG/JPEG output.

Render Options#

When making a render request, you can customize:

• format — Output format: png, jpeg, or pdf (default: png)
• quality — JPEG quality 1-100 (default: 90, only applies to JPEG)
• width — Override the template width in pixels
• height — Override the template height in pixels
• sizes — Array of { width, height } objects for multi-page PDFs (max 50 entries, PDF only)

Percentage Reference Dimension at Different Sizes#

When you override the width or height at render time (or use the sizes array for multi-page PDFs), the canvas aspect ratio may differ from the template's native proportions. This affects how percentage-based values are resolved for layer transforms and pin offsets.

Each percentage property — X, Y, Width, and Height on transforms, as well as each pin-edge offset — has a configurable reference dimension that determines whether the percentage resolves against the canvas width or canvas height:

• Width-based reference (default): The percentage is calculated as a fraction of the rendered canvas width. For example, 10% on a 1200px-wide canvas equals 120px, regardless of the canvas height. This produces uniform spacing from the left and top edges even when the aspect ratio changes.
• Height-based reference: The percentage is calculated as a fraction of the rendered canvas height. Use this when you want a value to scale proportionally with the vertical dimension — for instance, a bottom-margin offset that should stay visually consistent as the canvas grows taller.

Because width-based is the default, templates rendered at a different aspect ratio will maintain consistent horizontal spacing automatically. If you need certain elements to track the vertical dimension instead, switch their reference to height in the template editor (the W/H toggle next to each percentage field).

Tip: When generating a multi-page PDF with varied page sizes, review your percentage-based pin offsets and transform values to ensure elements position correctly across all target dimensions. Choosing the right reference dimension per property prevents unexpected shifts at non-native aspect ratios.

Multi-Page PDFs#

When using format: "pdf", you can generate a multi-page PDF by providing a sizes array. Each entry in the array becomes a separate page with its own dimensions, while the same template design and layer overrides are applied to every page.

{
  "template": "certificate",
  "format": "pdf",
  "sizes": [
    { "width": 1200, "height": 630 },
    { "width": 1080, "height": 1080 },
    { "width": 800, "height": 1200 }
  ],
  "layers": {
    "name": { "text": "Jane Doe" }
  }
}

If no sizes array is provided, a single-page PDF is generated using the width and height values (or the template defaults).

Render History#

All renders are tracked and visible on the Renders page. Each render record includes:

• Template name and version used
• Output format and dimensions
• Render duration in milliseconds
• File size of the output
• Status (completed, failed, processing)
• Any warnings generated during rendering

Rich Text in Renders#

Text layers support three content properties with descending priority: textRuns > richText > text. Use textRuns (structured JSON array) for full per-character styling control, richText (Markdown-like shorthand) for quick inline formatting, or text for plain strings. Rich text supports bold, italic, underline, strikethrough, color, highlight, font mixing, font size, superscript, and subscript within a single text frame. See Rich Text & Inline Styling for syntax details and examples.

Auto-Hide Visibility#

Layers with their visibility mode set to Auto are automatically hidden when their content is empty at render time. This means:

• If you omit a layer override for an Auto-visibility image layer, it will not appear in the output — no placeholder rectangle, no border, nothing.
• If you send an empty string for an Auto-visibility text layer, it will be completely removed from the rendered output.
• Each layer is evaluated independently. Hiding one layer does not affect any other layers.

This is especially useful for templates with optional elements like secondary speakers, optional badges, or conditional CTAs. Set those layers to Auto visibility in the editor, and simply omit them from your API call when they're not needed. See Layers — Visibility Modes for details.

Non-Blocking Renders#

RenderStack uses a non-blocking rendering approach. If an issue occurs with a specific element (such as a broken image URL), the render continues rather than failing entirely. Issues are reported as warnings in the response headers and render history.

Common warnings include:

Warning Code	Description
IMAGE_LOAD_FAILED	Could not load an image from the provided URL
IMAGE_URL_BLOCKED	Image URL was blocked for security reasons
QR_CODE_ERROR	QR code generation failed (invalid data or options)
CUSTOM_FONT_SUBSTITUTED	A custom font was replaced with Arial (plan does not include custom fonts)
UNKNOWN_LAYER	A layer name in the request doesn't match any template element
PRESIGNED_URL_IN_LAYER	A layer image src is a short-lived pre-signed URL (GCS or AWS). The image may render now but the URL will expire, making the render history and any future re-render unreliable. Use a stable, permanent URL instead.
MISSING_DYNAMIC_LAYER	A dynamic template element was not provided in layers. The template's default value was rendered in its place.

Render Limits#

• Maximum canvas dimensions: 8192 x 8192 pixels
• Maximum total pixels: 67,108,864 (8192 x 8192)
• Image URLs must be publicly accessible HTTPS or HTTP URLs
• Internal/private network URLs are blocked for security

Preview Downloads#

You can download a preview of your template directly from the template editor without making an API call. Click the Download Preview button (download icon) in the bottom-right corner of the canvas area. The server renders the output using the current editor state — including any unsaved changes — and downloads it in the template's configured output format (PNG, JPEG, or PDF).

This is useful for quick visual checks before integrating your template into a production workflow.

Viewing Renders#

Navigate to Renders in the sidebar to see your complete render history.

Render List#

The Renders page shows all generated images with the following information per entry:

• Thumbnail — A small preview of the rendered image (if available)
• Render ID — Unique identifier for the render
• Template ID — The template used to generate the image
• Dimensions — Output width and height
• Format — PNG, JPEG, or PDF
• Timestamp — When the render was created
• Duration — How long the render took in milliseconds
• Warnings — A badge showing the number of warnings (if any)
• Status — Completed, failed, or processing

Click any render to view its full details.

Render Detail Page#

The Render Detail page provides a comprehensive view of a single render:

• Image Preview — A large preview of the rendered output with options to open in a new tab or download
• Render ID — Full ID with a copy-to-clipboard button
• Details Card — Template link, dimensions, format, quality, and file size
• Timing Card — Render duration, creation time, and completion time
• Warnings — Expanded list of any warnings that occurred during rendering

From the detail page, you can click the template link to navigate directly to the template editor for the template used in that render.