What is an Orshot template made of?

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.

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

Top-Level Fields#

Reading a template also returns modifications and modifications_json. Orshot builds both from your parameterized layers. You never send them. See Modifications below.

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.

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

Every field of a page, its canvas, its layers, audio tracks and subtitles, with types and limits, is listed in the Template JSON reference. The sections below explain how the pieces fit together.

Pages#

Each page has its own canvas (size and background), so pages in one template can have different sizes. elements holds the page's layers. A higher zIndex draws on top; on a tie, the later layer draws on top. For video, a page also carries audioTracks, subtitle, videoDuration and motion. In a film, each page after the first can also carry a transitionIn. See Page, Canvas and Film.

Older templates may have a single audio object instead of audioTracks. It still plays; when both are present, audioTracks wins.

Audio and subtitles#

A page can hold several audio tracks, such as music, a generated voiceover and ambient sound. Each track has one source: an existing url, a tts narration recipe, or an sfx prompt. How many tracks a render may use depends on your plan. Add tts.parameterId to make the spoken text a modification. Subtitles are burned into video renders from an uploaded subtitle file or generated from the page audio. See Audio track and Subtitle.

Elements#

Elements (layers) are the building blocks of a page. Every element has an id, a type, a position and dimensions, plus a style object for its look. The types are text, image, element (SVG), shape, video and waveform. See Element and Element style.

{
  "id": "headline",
  "type": "text",
  "content": "Summer Sale!",
  "position": { "x": 50, "y": 100 },
  "dimensions": { "width": 400, "height": 80 },
  "style": {
    "fontSize": "48px",
    "fontFamily": "Inter",
    "color": "#000000",
    "lineHeight": 1.2
  },
  "parameterizable": true,
  "parameterId": "headline"
}

• Dynamic layers. Set parameterizable: true and a parameterId to let renders change the layer. A parameterId uses letters, digits and underscores, with no spaces, @, . or :. See Modifications below.
• Text takes its words in content. style.textMode decides what happens when text is longer than its box. In flow mode, text splits across extra pages; see Flowing content.
• Images and SVGs take a URL in content. On create, src is also accepted and saved as content.
• Shapes paint with style.fill, not backgroundColor.
• Waveforms draw one of the page's audio tracks, picked by waveTrack.
• Animation for video lives in transitions and motion. See Animations and Motion.

The template create and update APIs also accept flat x, y, width and height fields on elements and save them as position and dimensions. New integrations should send the nested form. Reading a template with an API key returns a summary of each page (page_id, name, thumbnail_url), not its layers.

Modifications#

Orshot builds a template's parameters from its parameterized layers each time the template is saved. You do not send them when you create or update a template. Reading a template with Get Studio Template returns them as modifications:

{
  "modifications": [
    {
      "key": "headline",
      "id": "headline",
      "type": "text",
      "description": "Headline — Text content",
      "help_text": "Headline — Text content",
      "element_name": "Headline",
      "example": "Summer Sale!",
      "page_number": 1,
      "page_id": "uuid-page-1"
    }
  ]
}

Each entry has the parameter key, its type (text, voiceText, imageUrl, videoUrl, backgroundColor, fill, color or stroke), the layer name, an example value taken from the template, and the page it belongs to. On a multi-page template every key has its page prefix, such as page1@headline and page2@headline. See Modification fields for every field.

Modifications JSON#

Get Studio Template also returns modifications_json, a simple key-value map of parameter keys to their default values:

{
  "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. It is a read-only view: you never send it.

Complete Example#

Here's a complete single-page template you can send to Create Template:

{
  "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": "72px",
            "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": "48px",
            "fontFamily": "Inter",
            "fontWeight": "600",
            "color": "#ff5733",
            "textAlign": "center"
          },
          "parameterizable": true,
          "parameterId": "price"
        }
      ]
    }
  ]
}

Reading this template back returns headline, product_image and price in modifications, and this modifications_json:

{
  "modifications_json": {
    "headline": "New Arrival",
    "product_image": "https://cdn.example.com/product.png",
    "price": "$99.99"
  }
}

Related#

• Template JSON reference - Every field, type and limit
• Template ID - Finding your template ID
• Modifications - Using modifications to customize templates
• Create Template (Enterprise) - Create templates via API