Sign in

v1

latestOpenAPI 3.1.02026-07-2665164286.3 KB
Templates

Generate Video from Template

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.

post/v3/templates/{template_id}

Path parameters

template_idstring required

Unique template identifier

Headers

Idempotency-Keystring

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Request body

variablesobject required

Template variable replacements, keyed by the variable name defined in the template

titlestring nullable

Title for the generated video

captionboolean

Whether to burn captions into the video

callback_idstring nullable

Opaque ID echoed back in webhook events for this video

callback_urlstring nullable

URL called with the video result in addition to registered webhook endpoints

folder_idstring nullable

Folder to place the generated video in

brand_voice_idstring nullable

Brand voice ID controlling pronunciation

fpsnumber

Output frame rate. One of 25, 30, or 60.

scene_idsstring[] 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_musicboolean

When true (default), background audio tracks move with their scenes. When false, tracks stay pinned to layout positions.

keep_text_vertically_centeredboolean

When true, replaced text elements are vertically re-centered based on their rendered height

include_gifboolean

Whether to include a GIF preview in the webhook payload

enable_sharingboolean

Whether the generated video's share page is publicly accessible

Response

Successful response

Example response

{
  "data": {
    "id": "v_abc123def456",
    "title": "My Generated Video",
    "created_at": 1711929600,
    "completed_at": 1711930200,
    "video_url": "https://files.heygen.ai/video/abc123.mp4",
    "thumbnail_url": "https://files.heygen.ai/thumb/abc123.jpg",
    "gif_url": "https://files.heygen.ai/gif/abc123.gif",
    "captioned_video_url": "https://files.heygen.ai/video/abc123_captioned.mp4",
    "subtitle_url": "https://files.heygen.ai/srt/abc123.srt",
    "duration": 30.5,
    "folder_id": "folder_abc123",
    "output_language": "en-US",
    "failure_code": "rendering_failed",
    "failure_message": "Avatar rendering timed out",
    "video_page_url": "https://app.heygen.com/video/abc123"
  }
}