Anatomy of a Template

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",
  "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
`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.

{
  "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

Canvas Object

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

{
  "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:

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

Field	Type	Description
`id`	String	Unique element identifier (UUID)
`type`	String	Element type: `text`, `image`, `rectangle`, `ellipse`, `shape`
`name`	String	Display name for the element
`x`	Number	X position from left edge
`y`	Number	Y position from top edge
`width`	Number	Element width in pixels
`height`	Number	Element height in pixels
`rotation`	Number	Rotation in degrees (0-360)
`opacity`	Number	Opacity (0-1)
`visible`	Boolean	Whether element is visible
`locked`	Boolean	Whether element is locked from editing
`parameterizable`	Boolean	Whether element can be modified via API
`parameterId`	String	Unique ID for API modifications (when parameterizable)

Text Elements

Text elements display text content with styling options:

{
  "id": "uuid-text-1",
  "type": "text",
  "content": "Summer Sale!",
  "x": 50,
  "y": 100,
  "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) or `overflow` (wraps naturally)

Image Elements

Image elements display images with fit options:

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

Property	Type	Description
`src`	String	Image source URL
`src_url`	String	Original image URL
`objectFit`	String	How image fits: `contain`, `cover`, `fill`
`borderRadius`	Number	Corner radius in pixels

Shape Elements

Shapes include rectangles, ellipses, and custom shapes:

{
  "id": "uuid-shape-1",
  "type": "rectangle",
  "x": 0,
  "y": 0,
  "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, providing a flat list for easy API access.

{
  "modifications": [
    {
      "id": "headline",
      "type": "text",
      "description": "Dynamic content for text element",
      "element": {
        "id": "uuid-element-1",
        "type": "text",
        "parameterId": "headline",
        "content": "Summer Sale!",
        "parameterizable": true
      }
    },
    {
      "id": "product_image",
      "type": "image",
      "description": "Dynamic content for image element",
      "element": {
        "id": "uuid-image-1",
        "type": "image",
        "parameterId": "product_image",
        "parameterizable": true
      }
    }
  ]
}

Modifications JSON

The modifications_json object provides a simple key-value map of parameter IDs 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.

Complete Example

Here's a complete single-page template structure:

{
  "name": "Product Promo",
  "description": "Product promotion template",
  "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": "rectangle",
          "name": "Background",
          "x": 0,
          "y": 0,
          "width": 1080,
          "height": 1080,
          "style": { "fill": "#f5f5f5" }
        },
        {
          "id": "headline-uuid",
          "type": "text",
          "name": "Headline",
          "content": "New Arrival",
          "x": 50,
          "y": 50,
          "width": 980,
          "height": 100,
          "style": {
            "fontSize": 72,
            "fontFamily": "Inter",
            "fontWeight": "bold",
            "color": "#000000",
            "textAlign": "center"
          },
          "parameterizable": true,
          "parameterId": "headline"
        },
        {
          "id": "product-uuid",
          "type": "image",
          "name": "Product Image",
          "src": "https://cdn.example.com/product.png",
          "x": 290,
          "y": 200,
          "width": 500,
          "height": 500,
          "style": { "objectFit": "contain" },
          "parameterizable": true,
          "parameterId": "product_image"
        },
        {
          "id": "price-uuid",
          "type": "text",
          "name": "Price",
          "content": "$99.99",
          "x": 50,
          "y": 750,
          "width": 980,
          "height": 80,
          "style": {
            "fontSize": 48,
            "fontFamily": "Inter",
            "fontWeight": "600",
            "color": "#ff5733",
            "textAlign": "center"
          },
          "parameterizable": true,
          "parameterId": "price"
        }
      ],
      "modifications": [
        { "id": "headline", "type": "text" },
        { "id": "product_image", "type": "image" },
        { "id": "price", "type": "text" }
      ]
    }
  ],
  "modifications": [
    {
      "id": "headline",
      "type": "text",
      "element": { "parameterId": "headline" }
    },
    {
      "id": "product_image",
      "type": "image",
      "element": { "parameterId": "product_image" }
    },
    { "id": "price", "type": "text", "element": { "parameterId": "price" } }
  ],
  "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

On this page