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.
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://..."
}| 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 |
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://..."
}
]
}| 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 |
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 are the building blocks of a template. Each element has a type, position, dimensions, and type-specific 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 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 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 |
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"
}
}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
}
}
]
}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.
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"
}
}