Create Template from Video

Creates a private template whose scenes, avatars, script and media are copied from one of your videos. The video must carry a draft in the current editor format, which every video generated with POST /v3/videos or saved in the HeyGen editor has; URL-to-Video and older editor videos are refused with template_source_unsupported. The video’s render status is not checked. The new template starts with no variables; declare them with PUT /v3/templates//variables or in the HeyGen editor, then generate videos from it with POST /v3/templates/. Returns the template detail.

POST /v3/templates

Create Template from Video

cURL

curl --request POST \
  --url https://api.heygen.com/v3/templates \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "video_id": "7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b",
  "name": "Q4 outreach"
}
'

201

{
  "data": {
    "id": "77e650952c024c6188a35e23e7088617",
    "name": "Quarterly Update",
    "thumbnail_url": "<string>",
    "aspect_ratio": "16:9",
    "created_at": 1711929600,
    "updated_at": 1711929600,
    "variables": {},
    "source_video_id": "<string>",
    "scene_ids": [
      "<string>"
    ],
    "scenes": [
      {
        "scene_id": "<string>",
        "script": "<string>",
        "variables": [
          {
            "name": "<string>",
            "variable_type": "<string>"
          }
        ]
      }
    ],
    "elements": [
      {
        "element_id": "<string>",
        "element_type": "avatar",
        "scene_id": "<string>",
        "bindable_as": [
          "text"
        ],
        "current": {
          "avatar_look_id": "<string>",
          "character_type": "avatar",
          "voice_id": "<string>",
          "text": "<string>",
          "url": "<string>",
          "play_style": "<string>",
          "volume": 123
        },
        "variable": "<string>",
        "text_variables": [
          "<string>"
        ]
      }
    ]
  }
}

Authorizations

ApiKeyAuthBearerAuth

x-api-key · string · header · required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

Idempotency-Key · string

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.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body

application/json

Request body for POST /v3/templates.

video_id · string · required

ID of a video in your workspace to turn into a template. The video must have been generated with POST /v3/videos or saved in the HeyGen editor; its draft becomes the template's starting point.

Minimum string length: 1

Example:

"7c1f0b2e3d4a4f5e8a9b0c1d2e3f4a5b"

name · string | null

Template name. Defaults to the source video's title.

Required string length: 1 - 255

Example:

"Q4 outreach"

Response

201

application/json

Created.

data · TemplateDetailV3 · object

Template detail including its variable schema, scenes, and bindable elements.

Show child attributes