What is an Orshot template made of?

A template is pages, layers, audio and parameters. Pages become outputs, layers hold content, and parameters are what the API can change.

Updated Aug 30, 2026

This guide explains the data structure of an Orshot Studio template. Understanding this structure is essential when creating templates via the API or working with template data programmatically.

Template Overview#

A Studio template consists of metadata, canvas settings, and pages containing elements. Templates support multi-page designs (like carousels) with each page having its own canvas settings and elements.

JSON

{
  "id": 12345,
  "name": "Summer Sale Banner",
  "description": "Promotional banner for summer campaign",
  "tags": ["sale", "summer"],
  "canvas_width": 1080,
  "canvas_height": 1080,
  "pages_data": [...],
  "modifications": [...],
  "modifications_json": {...},
  "thumbnail_url": "https://..."
}

Top-Level Fields#

Field	Type	Description
`id`	Integer	Unique template identifier (auto-generated)
`name`	String	Template name (max 255 characters)
`description`	String	Optional template description
`tags`	Array	Array of tag strings for categorization
`canvas_width`	Integer	Width of the first page in pixels (1-5000)
`canvas_height`	Integer	Height of the first page in pixels (1-5000)
`pages_data`	Array	Array of page objects
`modifications`	Array	Flattened list of all parameterizable elements
`modifications_json`	Object	Key-value map of parameter IDs to default values
`thumbnail_url`	String	URL to template preview thumbnail

Pages Data Structure#

The pages_data array contains page objects. Each page represents a slide in a carousel or a single canvas in a multi-page template.

JSON

{
  "pages_data": [
    {
      "id": "uuid-page-1",
      "name": "Page 1",
      "canvas": {
        "width": 1080,
        "height": 1080,
        "backgroundColor": "#ffffff"
      },
      "elements": [...],
      "modifications": [...],
      "thumbnail_url": "https://..."
    }
  ]
}

Page Object Fields#

Field	Type	Description
`id`	String	Unique page identifier (UUID recommended)
`name`	String	Display name for the page (e.g., "Page 1", "Cover Slide")
`canvas`	Object	Canvas settings for this page
`elements`	Array	Array of element objects on this page
`modifications`	Array	Parameterizable elements on this page
`thumbnail_url`	String	URL to page thumbnail preview
`audio`	Object	Page-level background audio — legacy single track (nullable)
`audioTracks`	Array	Page-level audio tracks array (nullable). Takes priority over `audio` when present
`subtitle`	Object	Page-level subtitle configuration (nullable)
`videoDuration`	Number	Saved video duration for this page in seconds (nullable)
`motion`	Object	Page-level motion: `look` (film grain/vignette) and `camera` moves (nullable). Presence switches the page's video rendering to the motion engine

Audio Tracks#

Each page can have multiple audio tracks, such as music, a generated voiceover, and ambient sound. A track uses an existing url, a tts narration recipe, or an sfx prompt. New templates use the audioTracks array. Legacy templates with a single audio object remain supported.

JSON

{
  "audioTracks": [
    {
      "id": "uuid-1",
      "label": "Background Music",
      "url": "https://storage.orshot.com/audio/music.mp3",
      "filename": "music.mp3",
      "duration": 60,
      "volume": 0.4,
      "fadeIn": 2,
      "fadeOut": 2,
      "trimStart": 0,
      "trimEnd": 60,
      "offset": 0,
      "loop": true,
      "muted": false,
      "enabled": true
    },
    {
      "id": "uuid-2",
      "label": "Voiceover",
      "tts": {
        "text": "Turn one design into a complete campaign.",
        "voiceId": "voice-id",
        "modelId": "flash",
        "parameterId": "voiceover"
      },
      "volume": 1,
      "fadeIn": 0.5,
      "fadeOut": 0.5,
      "trimStart": 0,
      "trimEnd": null,
      "offset": 2,
      "loop": false,
      "muted": false,
      "enabled": true
    }
  ]
}

Field	Type	Description
`id`	String	Unique track identifier (UUID)
`label`	String	Display label for the track
`url`	String	URL to the audio file
`tts`	Object	Generated narration recipe
`sfx`	Object	Generated ambient audio or sound-effect recipe
`filename`	String	Original filename
`duration`	Number	Audio file duration in seconds
`volume`	Number	Playback volume (0 to 1)
`fadeIn`	Number	Fade-in duration in seconds
`fadeOut`	Number	Fade-out duration in seconds
`trimStart`	Number	Start time for trimming (seconds)
`trimEnd`	Number	End time for trimming (seconds)
`offset`	Number	Delay before audio starts playing (seconds)
`loop`	Boolean	Loop the audio to fill the page duration
`muted`	Boolean	Mute this audio track
`enabled`	Boolean	Enable or disable this track

The maximum number of audio tracks per page depends on your plan.

For generated narration, tts.text is the script. tts.voiceId and tts.modelId select the delivery. Add tts.parameterId to make the spoken text available as a voiceText modification. Generated ambient audio uses sfx.prompt and an optional sfx.seconds value from 1 to 22.

Subtitle Object#

The subtitle field is null when no subtitles are configured. When set, it contains:

JSON

{
  "subtitle": {
    "url": "https://storage.orshot.com/subtitles/captions.srt",
    "filename": "captions.srt",
    "source": "upload",
    "enabled": true,
    "cueCount": 24,
    "fontSize": "30px",
    "fontFamily": "Inter, sans-serif",
    "fontWeight": "700",
    "color": "#ffffff",
    "background": "rgba(0,0,0,0.5)",
    "position": "bottom",
    "offset": 50,
    "mode": "word-by-word",
    "wordReveal": "highlight",
    "split": "word",
    "maxWordsPerLine": 4
  }
}

Field	Type	Description
`url`	String	URL to the subtitle file (.srt)
`filename`	String	Original filename
`source`	String	`"upload"` (user-uploaded SRT) or `"auto-audio"` (generated from page audio)
`enabled`	Boolean	Whether subtitles are active for this page
`cueCount`	Number	Number of subtitle cues in the file
`fontSize`	String	CSS font size
`fontFamily`	String	Font family
`fontWeight`	String	Font weight
`color`	String	Subtitle text color
`background`	String	Subtitle background color
`position`	String	`"bottom"`, `"center"`, or `"top"`
`offset`	Number	Distance from the positioned edge (pixels)
`mode`	String	`"phrase"` or `"word-by-word"`
`wordReveal`	String	`"appear"`, `"highlight"`, or `"align"`
`split`	String	Reveal by `"word"` or `"letter"`
`maxWordsPerLine`	Number	Word limit per line in word-by-word mode
`maxCharsPerLine`	Number	Character limit per line; overrides `maxWordsPerLine`

Canvas Object#

Each page has its own canvas settings, allowing different dimensions per page:

JSON

{
  "canvas": {
    "width": 1080,
    "height": 1080,
    "backgroundColor": "#ffffff",
    "backgroundImage": "",
    "borderWidth": 0,
    "borderColor": "rgba(0, 0, 0, 1)",
    "borderStyle": "solid"
  }
}

Field	Type	Description
`width`	Integer	Canvas width in pixels (1-5000)
`height`	Integer	Canvas height in pixels (1-5000)
`backgroundColor`	String	Background color (hex, rgb, rgba)
`backgroundImage`	String	Optional background image URL
`borderWidth`	Integer	Border width in pixels
`borderColor`	String	Border color
`borderStyle`	String	Border style (solid, dashed, etc.)

Elements#

Elements are the building blocks of a template. Each element has a type, position, dimensions, and type-specific properties.

Common Element Properties#

All elements share these base properties:

JSON

{
  "id": "uuid-element-1",
  "type": "text",
  "name": "Headline",
  "position": { "x": 50, "y": 100 },
  "dimensions": { "width": 400, "height": 80 },
  "rotation": 0,
  "zIndex": 1,
  "parameterizable": true,
  "parameterId": "headline"
}

Field	Type	Description
`id`	String	Unique element identifier (UUID)
`type`	String	Element type: `text`, `image`, `shape`, `element`, `video`, `waveform`, `container`
`name`	String	Display name for the element
`position`	Object	`{ x, y }` — position in pixels from the page's top-left corner
`dimensions`	Object	`{ width, height }` — size in pixels, or `"auto"` to size to content
`rotation`	Number	Rotation in degrees (0-360)
`zIndex`	Number	Stacking order — higher values render on top
`parameterizable`	Boolean	Whether element can be modified via API
`parameterId`	String	Unique ID for API modifications (when parameterizable)
`transitions`	Object	Enter/exit/ambient animations and visibility timing for video output (optional)
`motion`	Object	Cinematic motion behaviors — reveals, counters, choreography, SVG animation (optional). Presence switches the page's video rendering to the motion engine

Waveform Elements#

A waveform element visualizes one of the page's audio tracks. Set waveTrack to the zero-based track index. Use style.fill, barCount, barGap, waveAlign, minBarHeight, and borderRadius to control its appearance.

For backwards compatibility, the template create/update APIs also accept flat x, y, width, height fields on elements and normalize them into position/dimensions on save. New integrations should send the nested form, which is also the shape returned when reading templates back.

Text Elements#

Text elements display text content with styling options:

JSON

{
  "id": "uuid-text-1",
  "type": "text",
  "content": "Summer Sale!",
  "position": { "x": 50, "y": 100 },
  "dimensions": { "width": 400, "height": 80 },
  "style": {
    "fontSize": 48,
    "fontFamily": "Inter",
    "fontWeight": "bold",
    "color": "#000000",
    "textAlign": "center",
    "verticalAlign": "center",
    "letterSpacing": 0,
    "lineHeight": 1.2,
    "textMode": "fit"
  },
  "parameterizable": true,
  "parameterId": "headline"
}

Style Property	Type	Description
`fontSize`	Number	Font size in pixels
`fontFamily`	String	Font family name
`fontWeight`	String/Number	Font weight (normal, bold, 100-900)
`color`	String	Text color
`textAlign`	String	Horizontal alignment: `left`, `center`, `right`
`verticalAlign`	String	Vertical alignment: `flex-start`, `center`, `flex-end`
`letterSpacing`	Number	Letter spacing in pixels
`lineHeight`	Number	Line height multiplier
`textMode`	String	`fit` (scales to fit), `overflow` (wraps naturally), `truncate` (clips with ellipsis), or `flow` (splits across pages)

Flow Mode Properties

When textMode is set to "flow", these additional properties control how text splits across pages:

Property	Type	Description
`repeatOnOverflow`	Boolean	When `true`, this element appears on every overflow page
`flowZones`	Array	Custom zones for text placement on overflow pages (see below)
`flowBreakBehavior`	String	`"line"` (default), `"word"`, or `"char"` — where to split text
`flowMinLinesBeforeBreak`	Integer	Min lines at bottom of page before a break (default: 2)
`flowMinLinesAfterBreak`	Integer	Min lines at top of next page after a break (default: 2)

Each entry in flowZones has { y, height } — the Y position and height of the text area on that overflow page. The last zone repeats for all further pages. See Flowing Content for details.

Image Elements#

Image elements display images with fit options:

JSON

{
  "id": "uuid-image-1",
  "type": "image",
  "content": "https://cdn.example.com/product.png",
  "position": { "x": 100, "y": 200 },
  "dimensions": { "width": 300, "height": 300 },
  "style": {
    "objectFit": "contain",
    "borderRadius": 8
  },
  "parameterizable": true,
  "parameterId": "product_image"
}

Property	Type	Description
`content`	String	Image source URL (`src` is also accepted on create and normalized to `content`)
`objectFit`	String	How image fits: `contain`, `cover`, `fill`
`borderRadius`	Number	Corner radius in pixels

Shape Elements#

Shapes include rectangles, ellipses, and custom shapes:

JSON

{
  "id": "uuid-shape-1",
  "type": "shape",
  "shapeType": "rectangle",
  "position": { "x": 0, "y": 0 },
  "dimensions": { "width": 1080, "height": 200 },
  "style": {
    "fill": "#ff5733",
    "backgroundColor": "#ff5733",
    "borderRadius": 0,
    "borderWidth": 0,
    "borderColor": "#000000"
  }
}

Modifications#

The modifications array at the template level contains all parameterizable elements across all pages in a lean format. Each entry stores the parameter metadata without duplicating the full element object.

JSON

{
  "modifications": [
    {
      "id": "headline",
      "type": "text",
      "default_value": "Summer Sale!",
      "element_id": "uuid-element-1",
      "element_name": "Headline",
      "element_type": "text",
      "is_hidden": false,
      "page_number": 1
    },
    {
      "id": "product_image",
      "type": "imageUrl",
      "default_value": "https://cdn.example.com/product.png",
      "element_id": "uuid-image-1",
      "element_name": "Product Image",
      "element_type": "image",
      "is_hidden": false,
      "page_number": 1
    }
  ]
}

Modification Fields (stored format)#

Field	Type	Description
`id`	String	Parameter key. Multi-page templates use `page2@headline` format for pages beyond page 1
`type`	String	`text`, `voiceText`, `imageUrl`, `videoUrl`, `backgroundColor`, `fill`, `color`, `stroke`
`default_value`	String	Default value extracted from the element
`element_id`	String	UUID of the source element
`element_name`	String	Layer name of the element (from `layerName` or `name`)
`element_type`	String	Element type (`text`, `image`, `rectangle`, etc.)
`is_hidden`	Boolean	Whether the element is hidden in the editor
`page_number`	Integer	1-based page number

When returned via API endpoints, modifications are formatted with additional fields (key, description, help_text, example, page_id) for convenience. See the API reference for the response format.

Modifications JSON#

The modifications_json object provides a simple key-value map of parameter IDs to their default values:

JSON

{
  "modifications_json": {
    "headline": "Summer Sale!",
    "subtitle": "Up to 50% off",
    "product_image": "https://cdn.example.com/product.png",
    "price": "$99.99"
  }
}

This format is useful for quickly understanding what parameters a template accepts and their default values.

Complete Example#

Here's a complete single-page template structure:

JSON

{
  "name": "Product Promo",
  "description": "Product promotion template",
  "tags": ["promo", "product"],
  "canvas_width": 1080,
  "canvas_height": 1080,
  "pages_data": [
    {
      "id": "page-1-uuid",
      "name": "Page 1",
      "canvas": {
        "width": 1080,
        "height": 1080,
        "backgroundColor": "#ffffff"
      },
      "elements": [
        {
          "id": "bg-uuid",
          "type": "shape",
          "shapeType": "rectangle",
          "name": "Background",
          "position": { "x": 0, "y": 0 },
          "dimensions": { "width": 1080, "height": 1080 },
          "zIndex": 1,
          "style": { "fill": "#f5f5f5" }
        },
        {
          "id": "headline-uuid",
          "type": "text",
          "name": "Headline",
          "content": "New Arrival",
          "position": { "x": 50, "y": 50 },
          "dimensions": { "width": 980, "height": 100 },
          "zIndex": 2,
          "style": {
            "fontSize": 72,
            "fontFamily": "Inter",
            "fontWeight": "bold",
            "color": "#000000",
            "textAlign": "center"
          },
          "parameterizable": true,
          "parameterId": "headline"
        },
        {
          "id": "product-uuid",
          "type": "image",
          "name": "Product Image",
          "content": "https://cdn.example.com/product.png",
          "position": { "x": 290, "y": 200 },
          "dimensions": { "width": 500, "height": 500 },
          "zIndex": 3,
          "style": { "objectFit": "contain" },
          "parameterizable": true,
          "parameterId": "product_image"
        },
        {
          "id": "price-uuid",
          "type": "text",
          "name": "Price",
          "content": "$99.99",
          "position": { "x": 50, "y": 750 },
          "dimensions": { "width": 980, "height": 80 },
          "zIndex": 4,
          "style": {
            "fontSize": 48,
            "fontFamily": "Inter",
            "fontWeight": "600",
            "color": "#ff5733",
            "textAlign": "center"
          },
          "parameterizable": true,
          "parameterId": "price"
        }
      ],
      "modifications": []
    }
  ],
  "modifications": [
    {
      "id": "headline",
      "type": "text",
      "default_value": "New Arrival",
      "element_id": "headline-uuid",
      "element_name": "Headline",
      "element_type": "text",
      "is_hidden": false,
      "page_number": 1
    },
    {
      "id": "product_image",
      "type": "imageUrl",
      "default_value": "https://cdn.example.com/product.png",
      "element_id": "product-uuid",
      "element_name": "Product Image",
      "element_type": "image",
      "is_hidden": false,
      "page_number": 1
    },
    {
      "id": "price",
      "type": "text",
      "default_value": "$99.99",
      "element_id": "price-uuid",
      "element_name": "Price",
      "element_type": "text",
      "is_hidden": false,
      "page_number": 1
    }
  ],
  "modifications_json": {
    "headline": "New Arrival",
    "product_image": "https://cdn.example.com/product.png",
    "price": "$99.99"
  }
}

Template ID - Finding your template ID
Modifications - Using modifications to customize templates
Create Template (Enterprise) - Create templates via API

←

What is a template ID?

What are modifications?

→

Was this page helpful?

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
100 free credits a month, no credit card required

What is an Orshot template made of?

Template Overview#

Top-Level Fields#

Pages Data Structure#

Page Object Fields#

Audio Tracks#

Subtitle Object#

Canvas Object#

Elements#

Common Element Properties#

Waveform Elements#

Text Elements#

Flow Mode Properties

Image Elements#

Shape Elements#

Modifications#

Modification Fields (stored format)#

Modifications JSON#

Complete Example#

Related#

Ready to automate?