Generate Template Variants

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.

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"
  }),
});

Rate Limits#

URL Parameters#

Request Body Parameters#

Variant Object Structure#

Each variant in the variants array should include:

Output Modes#

Query Parameters#

Response Fields#

Common Fields#

Variant Result Fields (varies by output mode)#

Thumbnails Object Structure#

When ?includeThumbnails=true is passed with output: "templates", each new template variant includes a nested thumbnails object:

For output: "pages", each variant entry gets a flat thumbnail_url field instead (the variant itself represents a single page), with an optional thumbnail_error field if rendering failed.

When ?includeThumbnails is not passed, thumbnails are generated asynchronously after the response. For pages mode, they appear on the source template; for templates mode, on each newly created template.

How AI Variant Generation Works#

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

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

Supported Transformations#

Error Responses#

Best Practices#

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