---
title: "Create Variant"
method: POST
path: "/v1/template/{template_id}/variant"
tags: ["Variants"]
---

# Create Variant

`POST /v1/template/{template_id}/variant`

## Request

- Base URL: `https://layerre.com` (the document declares no server; this is the origin it was published from)
- URL: `https://layerre.com/v1/template/{template_id}/variant`
- Auth: HTTP bearer

Render one variant per request from a template, optionally overriding layers.

Overrides is an array of objects with layer_id (from GET /v1/template/{template_id})
and optional properties; layers you omit keep template defaults.

## Path parameters

- `template_id` string, uuid, required

## Request body

- VariantCreateUpdateRequest
  - `overrides` VariantOverrideOptional[], nullable: Array of per-layer overrides; each entry has layer_id from GET /v1/template/{template_id} and optional properties.
    - `layer_id` string, uuid, required: UUID of the layer to override. Must match a layer in the target template (retrieve via GET /v1/template/{template_id}).
    - `x` number, nullable: X position override in pixels. Omit to keep template default.
    - `y` number, nullable: Y position override in pixels. Omit to keep template default.
    - `properties` FlexibleLayerProperties: Flexible layer properties that can handle any combination of text and image properties
      - `width` number, nullable: Layer width in pixels
      - `height` number, nullable: Layer height in pixels
      - `color` string, nullable: Color in hex format (#RRGGBB)
      - `rotation` number, nullable: Rotation angle in degrees
      - `text` string, nullable: Text content
      - `font_size` number, nullable: Font size in pixels
      - `font_name` string, nullable: Font family name
      - `font_style` FontStyle: Font styling properties
        - `weight` string, nullable
        - `italic` boolean, nullable
        - `underline` boolean, nullable
      - `text_align` 'left' | 'center' | 'right' | 'justify': Text alignment options
      - `text_direction` 'rtl', nullable: Text direction; only set for right-to-left text (Arabic, Hebrew, etc.). Absent/null means LTR.
      - `letter_spacing` number, nullable: Letter spacing in pixels
      - `line_spacing` number, nullable: Line spacing in pixels
      - `vertical_align` string, nullable: Vertical alignment for text (e.g. 'middle')
      - `img_url` string, nullable: Image URL for image layers: public HTTPS, data URI, or Google Drive link shared for viewing.
      - `image_fit` 'cover' | 'contain'
      - `image_position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
      - `signed_url_expiry` string, date-time, nullable
      - `opacity` number, nullable: Opacity value (0.0 = fully transparent, 1.0 = fully opaque)
      - `flip_horizontal` boolean, nullable: Flip the layer horizontally
      - `flip_vertical` boolean, nullable: Flip the layer vertically
  - `width` integer, nullable: Variant width in pixels
  - `height` integer, nullable: Variant height in pixels
  - `export_type` 'png' | 'pdf' | 'jpeg' | 'webp': Export format options for variants
  - `page_number` integer, nullable: Page index to render (0-based). Only layers on this page are included.

## Response `201`

Variant created successfully

- VariantResponse
  - `id` string, uuid, required
  - `template_id` string, uuid, required
  - `url` string, required: Rendered variant URL
  - `signed_url_expiry` string, date-time, nullable
  - `width` integer, required: Variant width in pixels
  - `height` integer, required: Variant height in pixels
  - `overrides` VariantOverrideOptional[], required: List of layer overrides for the variant
    - `layer_id` string, uuid, required: UUID of the layer to override. Must match a layer in the target template (retrieve via GET /v1/template/{template_id}).
    - `x` number, nullable: X position override in pixels. Omit to keep template default.
    - `y` number, nullable: Y position override in pixels. Omit to keep template default.
    - `properties` FlexibleLayerProperties: Flexible layer properties that can handle any combination of text and image properties
      - `width` number, nullable: Layer width in pixels
      - `height` number, nullable: Layer height in pixels
      - `color` string, nullable: Color in hex format (#RRGGBB)
      - `rotation` number, nullable: Rotation angle in degrees
      - `text` string, nullable: Text content
      - `font_size` number, nullable: Font size in pixels
      - `font_name` string, nullable: Font family name
      - `font_style` FontStyle: Font styling properties
        - `weight` string, nullable
        - `italic` boolean, nullable
        - `underline` boolean, nullable
      - `text_align` 'left' | 'center' | 'right' | 'justify': Text alignment options
      - `text_direction` 'rtl', nullable: Text direction; only set for right-to-left text (Arabic, Hebrew, etc.). Absent/null means LTR.
      - `letter_spacing` number, nullable: Letter spacing in pixels
      - `line_spacing` number, nullable: Line spacing in pixels
      - `vertical_align` string, nullable: Vertical alignment for text (e.g. 'middle')
      - `img_url` string, nullable: Image URL for image layers: public HTTPS, data URI, or Google Drive link shared for viewing.
      - `image_fit` 'cover' | 'contain'
      - `image_position` 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
      - `signed_url_expiry` string, date-time, nullable
      - `opacity` number, nullable: Opacity value (0.0 = fully transparent, 1.0 = fully opaque)
      - `flip_horizontal` boolean, nullable: Flip the layer horizontally
      - `flip_vertical` boolean, nullable: Flip the layer vertically
  - `page_number` integer: Page index this variant was rendered from (0-based)
  - `is_combined_pdf` boolean: True when this variant is a multi-section combined PDF
  - `combined_section_count` integer, nullable: Number of variant sections merged into a combined PDF
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `warnings` string[], nullable

## Other responses

- `400`: Bad request - invalid input or no valid layers found
- `403`: Plan limit exceeded
- `404`: Template not found
- `422`: Validation Error
- `500`: Internal server error
- `504`: Render timeout — retry the same request

---

[API](https://skmtc.dev/layerre/apis/layerre-api-documentation.md) · [All operations](https://skmtc.dev/layerre/apis/layerre-api-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/layerre/apis/layerre-api-documentation/revisions/66b268766603?raw)