---
title: "Generate Video from Template"
method: POST
path: "/v3/templates/{template_id}"
tags: ["Templates"]
---

# Generate Video from Template

`POST /v3/templates/{template_id}`

Generates a video from the template by replacing its variables (text, image, video, audio, character, voice). Use scene_ids to select, reorder, or repeat scenes — scenes must already exist in the template; the API cannot create new ones. Returns the created video object; poll GET /v3/videos/{video_id} or use webhooks for completion. Idempotent replays return the original creation-time snapshot (status and URLs as of the first request), not the video's current state.

## Path parameters

- `template_id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- GenerateFromTemplateV3Request — Request body for POST /v3/templates/{template_id}.
  - `variables` object, required — Template variable replacements, keyed by the variable name defined in the template
  - `title` string, nullable — Title for the generated video
  - `caption` boolean — Whether to burn captions into the video
  - `subtitles` TemplateSubtitleSettings — Output subtitle style settings (mirrors the /v3/videos subtitles input).
    - `preset_name` string, required — Subtitle preset name, e.g. 'classic', 'bold', 'bright'
    - `alignment` integer, nullable — Subtitle alignment
    - `disable_highlight` boolean, nullable — Override the preset's word-highlight style
    - `font_size` integer, nullable — Font size override for the preset
    - `position` TemplateSubtitlePosition — Subtitle position override.
      - `x` number — Horizontal subtitle position
      - `y` number — Vertical subtitle position
  - `callback_id` string, nullable — Opaque ID echoed back in webhook events for this video
  - `callback_url` string, nullable — URL called with the video result in addition to registered webhook endpoints
  - `folder_id` string, nullable — Folder to place the generated video in
  - `brand_voice_id` string, nullable — Brand voice ID controlling pronunciation
  - `dimension` TemplateVideoDimension — Output resolution override. Must keep the template's aspect ratio.
    - `width` integer, required — Output video width in pixels (even number, 128-4096)
    - `height` integer, required — Output video height in pixels (even number, 128-4096)
  - `fps` number — Output frame rate. One of 25, 30, or 60.
  - `scene_ids` string[], nullable — Scene IDs to render, in order (repeats allowed). Scenes must already exist in the template; the API can select, reorder, and repeat scenes but cannot create new ones. Omit to render all scenes in template order.
  - `reorder_music` boolean — When true (default), background audio tracks move with their scenes. When false, tracks stay pinned to layout positions.
  - `keep_text_vertically_centered` boolean — When true, replaced text elements are vertically re-centered based on their rendered height
  - `include_gif` boolean — Whether to include a GIF preview in the webhook payload
  - `enable_sharing` boolean — Whether the generated video's share page is publicly accessible

## Response `200`

Successful response

- object
  - `data` VideoDetail — Video resource returned by list and detail endpoints. If ``output_language`` is present the video is a translated video; otherwise it is a generated video.
    - `id` string, required — Unique video identifier
    - `title` string, nullable — Video title
    - `status` 'pending' | 'processing' | 'completed' | 'failed', required
    - `created_at` integer, nullable — Unix timestamp of creation
    - `completed_at` integer, nullable — Unix timestamp when video generation finished
    - `video_url` string, nullable — Presigned URL to download the video file
    - `thumbnail_url` string, nullable — URL to video thumbnail image
    - `gif_url` string, nullable — URL to animated GIF preview
    - `captioned_video_url` string, nullable — Presigned URL to download the video file with captions burned in
    - `subtitle_url` string, nullable — Presigned URL to download the SRT subtitle file
    - `duration` number, nullable — Video duration in seconds
    - `folder_id` string, nullable — ID of containing folder
    - `output_language` string, nullable — BCP-47 output language code. Present only for translated videos.
    - `failure_code` string, nullable — Machine-readable failure reason. Only present when status is failed.
    - `failure_message` string, nullable — Human-readable failure description. Only present when status is failed.
    - `video_page_url` string, nullable — URL to the video page in the HeyGen app

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication failed
- `404` — Resource not found
- `409` — A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/heygen/apis/heygen-external-api.md) · [All operations](https://skmtc.net/heygen/apis/heygen-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heygen/heygen-external-api/versions/e2e54726e210/schema)