POST: Generate Template Variants

Enterprise Only

This is an Enterprise only private endpoint. Checkout the Enterprise Pricing to get access.

Generate multiple size variants of an existing studio template using AI-powered layout adaptation. The AI intelligently repositions and resizes elements to fit new dimensions while maintaining visual hierarchy and design integrity.

By default, generated variants are added as new pages to the source template. You can also create them as separate templates using the output parameter.

AI Credits

Each variant generated consumes 1 AI credit from your plan. Credits are validated before generation and deducted after successful completion.

Endpoint

https://api.orshot.com/v1/studio/templates/:templateId/generate-variants

Request

// Add variants as new pages to the same template
await fetch("https://api.orshot.com/v1/studio/templates/12345/generate-variants", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    variants: [
      { width: 1080, height: 1080 },
      { width: 1080, height: 1920 }
    ],
    output: "pages"
  }),
});

// Create new templates for each variant
await fetch("https://api.orshot.com/v1/studio/templates/12345/generate-variants", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    variants: [
      { width: 1080, height: 1080 },
      { width: 1080, height: 1920 },
      { width: 1200, height: 628 }
    ],
    output: "templates"
  }),
});

{
  "success": true,
  "source_template_id": 12345,
  "source_page": 1,
  "output_mode": "pages",
  "variants": [
    {
      "variant_index": 0,
      "width": 1080,
      "height": 1080,
      "page_index": 1,
      "page_id": "generated-page-uuid-1",
      "page_name": "Square"
    },
    {
      "variant_index": 1,
      "width": 1080,
      "height": 1920,
      "page_index": 2,
      "page_id": "generated-page-uuid-2",
      "page_name": "Story"
    }
  ]
}

{
  "success": true,
  "source_template_id": 12345,
  "source_page": 1,
  "output_mode": "templates",
  "variants": [
    {
      "variant_index": 0,
      "width": 1080,
      "height": 1080,
      "template_id": 12346,
      "template_name": "Square"
    },
    {
      "variant_index": 1,
      "width": 1080,
      "height": 1920,
      "template_id": 12347,
      "template_name": "Story"
    },
    {
      "variant_index": 2,
      "width": 1200,
      "height": 628,
      "template_id": 12348,
      "template_name": "OG Image"
    }
  ]
}

Rate Limits

Limit	Value
Requests per minute	30
Max variants per request	10

URL Parameters

Parameter	Type	Required	Description
`templateId`	Integer	Yes	The ID of the source template to generate variants from

Request Body Parameters

Parameter	Type	Required	Default	Description
`variants`	Array	Yes	-	Array of target dimensions for variants
`page_number`	Integer	No	`1`	Which page of the template to use as source
`output`	String	No	`"pages"`	Output mode: `"pages"` or `"templates"`

Variant Object Structure

Each variant in the variants array should include:

Field	Type	Required	Description
`width`	Integer	Yes	Target width in pixels (1-5000)
`height`	Integer	Yes	Target height in pixels (1-5000)
`name`	String	No	Custom name for the generated page or template

Output Modes

Mode	Description
`pages`	Adds each variant as a new page to the source template
`templates`	Creates a new template for each variant in the same workspace

Response Fields

Common Fields

Field	Type	Description
`success`	Boolean	Whether the operation was successful
`source_template_id`	Integer	ID of the source template
`source_page`	Integer	Page number used as source
`output_mode`	String	The output mode used
`variants`	Array	Array of generated variant results

Variant Result Fields (varies by output mode)

Field	Output Mode	Type	Description
`variant_index`	All	Integer	Index of this variant in the request
`width`	All	Integer	Width of the variant
`height`	All	Integer	Height of the variant
`page_index`	`pages`	Integer	Index of the new page in the template
`page_id`	`pages`	String	UUID of the new page
`page_name`	`pages`	String	Name of the new page
`template_id`	`templates`	Integer	ID of the newly created template
`template_name`	`templates`	String	Name of the newly created template
`error`	All	String	Error message if this variant failed

How AI Variant Generation Works

The AI analyzes your source design and intelligently adapts it to new dimensions:

Element Analysis: Identifies element types, positions, and relationships
Hierarchy Detection: Understands which elements are backgrounds, headlines, images, etc.
Layout Adaptation: Repositions and resizes elements to fit new dimensions
Proportion Preservation: Maintains relative sizes and spacing relationships
Text Handling: Adjusts text box sizes and font sizes to prevent overflow

Supported Transformations

From	To	Behavior
Landscape	Square	Stacks elements vertically, enlarges hero images
Landscape	Portrait	Vertical stacking, maximizes vertical space usage
Square	Landscape	Horizontal arrangement, side-by-side layout
Portrait	Square	Redistributes vertical space

Error Responses

Status Code	Error	Description
400	Validation failed	Invalid variants array or dimensions
400	Invalid page_number	Specified page doesn't exist in template
403	Insufficient AI credits	Not enough AI credits available
403	Access Forbidden	Invalid API key or template not in workspace
404	Template not found	Template ID doesn't exist
429	Rate limit exceeded	Too many requests (max 30/min)
500	Internal server error	AI generation or server error

Best Practices

Source Quality: Use a well-designed source template for best AI results
Batch Sizes: Generate up to 10 variants per request for optimal performance
Output Selection:
- Use pages to keep all variants in one template (carousels)
- Use templates for independent templates that render separately
Page Selection: For multi-page templates, specify which page to use as source
Dimensions: AI works best when aspect ratio changes aren't too extreme

POST: Generate Template Variants

On this page