# Generate Template Variants > Generate multiple size variants of a template using AI - **URL**: https://orshot.com/docs/api-reference/enterprise-generate-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```markdown tab="Endpoint" https://api.orshot.com/v1/studio/templates/:templateId/generate-variants ```## Request ```js // 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 ", }, body: JSON.stringify({ variants: [ { width: 1080, height: 1080 }, { width: 1080, height: 1920 } ], output: "pages" }), }); ``` ```js // 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 ", }, body: JSON.stringify({ variants: [ { width: 1080, height: 1080 }, { width: 1080, height: 1920 }, { width: 1200, height: 628 } ], output: "templates" }), }); ``` ```json { "success": true, "source_template_id": 12345, "source_page": 1, "source_page_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "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" } ] } ``` ```json { "success": true, "source_template_id": 12345, "source_page": 1, "source_page_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "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" } ] } ``` ```json { "success": true, "source_template_id": 12345, "source_page": 1, "source_page_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "output_mode": "pages", "variants": [ { "variant_index": 0, "width": 1080, "height": 1080, "page_index": 1, "page_id": "generated-page-uuid-1", "page_name": "Square", "thumbnail_url": "https://storage.orshot.com/cloud/w-50/renders/thumbnails/sq1.png" }, { "variant_index": 1, "width": 1080, "height": 1920, "page_index": 2, "page_id": "generated-page-uuid-2", "page_name": "Story", "thumbnail_url": "https://storage.orshot.com/cloud/w-50/renders/thumbnails/st1.png" } ] } ``` ```json { "success": true, "source_template_id": 12345, "source_page": 1, "source_page_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "output_mode": "templates", "variants": [ { "variant_index": 0, "width": 1080, "height": 1080, "template_id": 12346, "template_name": "Square", "thumbnails": { "success": true, "pages": [ { "page": 1, "page_id": "tpl-1-page-uuid", "thumbnail_url": "https://storage.orshot.com/cloud/w-50/renders/thumbnails/sq2.png", "error": null } ] } }, { "variant_index": 1, "width": 1080, "height": 1920, "template_id": 12347, "template_name": "Story", "thumbnails": { "success": true, "pages": [ { "page": 1, "page_id": "tpl-2-page-uuid", "thumbnail_url": "https://storage.orshot.com/cloud/w-50/renders/thumbnails/st2.png", "error": null } ] } } ] } ``` ## 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 | ## Query Parameters | Parameter | Type | Required | Default | Description | | ------------------- | ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `includeThumbnails` | Boolean | No | `false` | When `true`, thumbnails are rendered for each newly created variant and returned inline in the response. When `false` or absent, thumbnails are generated asynchronously. Shape of the inline thumbnail depends on `output` mode (see below). | ## 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 | | `source_page_id` | String | Stable UUID of the source page. Use this to reliably reference the source page even after template pages are reordered | | `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 | | `thumbnail_url` | `pages` | String\|null | Only present when `?includeThumbnails=true`. Public URL of the thumbnail PNG for this variant's page. `null` if rendering this page failed | | `thumbnail_error` | `pages` | String | Present only when `?includeThumbnails=true` and this variant's thumbnail failed to render. Contains the error message | | `thumbnails` | `templates` | Object | Only present when `?includeThumbnails=true`. See [Thumbnails Object Structure](#thumbnails-object-structure) below | | `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 | ### Thumbnails Object Structure When `?includeThumbnails=true` is passed with `output: "templates"`, each new template variant includes a nested `thumbnails` object: | Field | Type | Description | | ----------------------- | ------------ | ----------------------------------------------------------------------------- | | `success` | Boolean | `true` if at least one page rendered successfully | | `pages[].page` | Integer | 1-based page number | | `pages[].page_id` | String | Stable UUID of the page | | `pages[].thumbnail_url` | String\|null | Public URL of the thumbnail PNG. `null` if this page failed | | `pages[].error` | String\|null | Error message if this page failed. `null` on success | 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 | 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 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