> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Template

> Returns template details including its variable schema (with current default values) and scenes. Variable defaults are returned in the same shape the generate request accepts, so a response can be edited and posted back. Only draft version 4 templates (the current editor format) are supported.



## OpenAPI

````yaml /openapi/external-api.json get /v3/templates/{template_id}
openapi: 3.1.0
info:
  title: HeyGen External API
  version: 1.0.0
  description: >-
    HeyGen's external API for programmatic AI video creation. See
    https://docs.heygen.com for full documentation.
  contact:
    name: HeyGen Product Infra
    url: https://heygen.com
servers:
  - url: https://api.heygen.com
    description: Production
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Video Agent
    description: Create videos from text prompts using AI
  - name: Videos
    description: Create, list, retrieve, and delete videos
  - name: Templates
    description: Generate videos from reusable templates by replacing their variables
  - name: Voices
    description: Text-to-speech and voice management
  - name: Audio
    description: Search the background-music and sound-effects catalog
  - name: Video Translate
    description: Translate videos into other languages
  - name: AI Clipping
    description: Turn long-form videos into ready-to-share short clips with captions
  - name: Batches
    description: Create and track batches of videos.
  - name: User
    description: Account information and billing
  - name: Avatars
    description: List and manage avatars and looks
  - name: Avatar Realtime
    description: >-
      Low-latency streaming avatar sessions — create a stream, poll for its HLS
      URL, push text, consume per-word timestamps
  - name: Assets
    description: Upload files for use in video creation
  - name: Webhooks
    description: Manage webhook endpoints and events
  - name: Lipsync
    description: Dub or replace audio on existing videos
  - name: Brand
    description: >-
      Brand-related resources — brand kits (colors, fonts, logos) and brand
      glossaries (custom term translations)
  - name: HyperFrames
    description: Render HyperFrames composition zips into video — separate from /v3/videos
paths:
  /v3/templates/{template_id}:
    get:
      tags:
        - Templates
      summary: Get Template
      description: >-
        Returns template details including its variable schema (with current
        default values) and scenes. Variable defaults are returned in the same
        shape the generate request accepts, so a response can be edited and
        posted back. Only draft version 4 templates (the current editor format)
        are supported.
      operationId: getTemplateV3
      parameters:
        - name: template_id
          in: path
          required: true
          schema:
            type: string
          description: Unique template identifier
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/TemplateDetailV3'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: authentication_failed
                  message: Invalid or expired API key. Verify your x-api-key header.
                  param: null
                  doc_url: null
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: template_not_found
                  message: Template not found.
                  param: null
                  doc_url: null
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: rate_limit_exceeded
                  message: >-
                    Too many requests. Retry after the duration specified in the
                    Retry-After header.
                  param: null
                  doc_url: null
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    TemplateDetailV3:
      description: Template detail including its variable schema and scenes.
      properties:
        id:
          description: Unique template identifier
          examples:
            - 77e650952c024c6188a35e23e7088617
          title: Id
          type: string
        name:
          description: Template name
          examples:
            - Quarterly Update
          title: Name
          type: string
        thumbnail_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: URL to the template thumbnail image
          title: Thumbnail Url
        aspect_ratio:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Template aspect ratio
          examples:
            - '16:9'
          title: Aspect Ratio
        created_at:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: Unix timestamp of creation
          examples:
            - 1711929600
          title: Created At
        updated_at:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          description: Unix timestamp of last update
          examples:
            - 1711929600
          title: Updated At
        variables:
          additionalProperties:
            discriminator:
              mapping:
                audio:
                  $ref: '#/components/schemas/TemplateAudioVariable'
                character:
                  $ref: '#/components/schemas/TemplateCharacterVariable'
                image:
                  $ref: '#/components/schemas/TemplateImageVariable'
                text:
                  $ref: '#/components/schemas/TemplateTextVariable'
                video:
                  $ref: '#/components/schemas/TemplateVideoVariable'
                voice:
                  $ref: '#/components/schemas/TemplateVoiceVariable'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/TemplateTextVariable'
              - $ref: '#/components/schemas/TemplateImageVariable'
              - $ref: '#/components/schemas/TemplateVideoVariable'
              - $ref: '#/components/schemas/TemplateAudioVariable'
              - $ref: '#/components/schemas/TemplateCharacterVariable'
              - $ref: '#/components/schemas/TemplateVoiceVariable'
          description: >-
            Variables defined in the template with their current default values,
            keyed by variable name
          title: Variables
          type: object
        scene_ids:
          description: Scene IDs in template order
          items:
            type: string
          title: Scene Ids
          type: array
        scenes:
          description: Scenes defined in the template
          items:
            $ref: '#/components/schemas/TemplateSceneV3'
          title: Scenes
          type: array
      required:
        - id
        - name
      title: TemplateDetailV3
      type: object
    StandardAPIError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: invalid_parameter
        message:
          type: string
          description: Human-readable error message
          example: Video not found
        param:
          type:
            - string
            - 'null'
          description: Which request field caused the error
        doc_url:
          type:
            - string
            - 'null'
          description: Link to error documentation
      required:
        - code
        - message
    TemplateAudioVariable:
      additionalProperties: false
      description: Replaces an audio placeholder in the template.
      properties:
        type:
          const: audio
          description: Variable type discriminator
          title: Type
          type: string
        asset:
          description: Audio to place. Accepts url, asset_id, or base64 input.
          discriminator:
            mapping:
              asset_id:
                $ref: '#/components/schemas/AssetId'
              base64:
                $ref: '#/components/schemas/AssetBase64'
              url:
                $ref: '#/components/schemas/AssetUrl'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/AssetUrl'
            - $ref: '#/components/schemas/AssetId'
            - $ref: '#/components/schemas/AssetBase64'
          title: Asset
      required:
        - type
        - asset
      title: TemplateAudioVariable
      type: object
    TemplateCharacterVariable:
      additionalProperties: false
      description: Replaces an avatar or talking-photo placeholder in the template.
      properties:
        type:
          const: character
          description: Variable type discriminator
          title: Type
          type: string
        character_id:
          description: Avatar ID or talking photo ID to place
          minLength: 1
          title: Character Id
          type: string
        character_type:
          default: avatar
          description: Kind of character the character_id refers to
          enum:
            - avatar
            - talking_photo
          title: Character Type
          type: string
      required:
        - type
        - character_id
      title: TemplateCharacterVariable
      type: object
    TemplateImageVariable:
      additionalProperties: false
      description: Replaces an image placeholder in the template.
      properties:
        type:
          const: image
          description: Variable type discriminator
          title: Type
          type: string
        asset:
          description: Image to place. Accepts url, asset_id, or base64 input.
          discriminator:
            mapping:
              asset_id:
                $ref: '#/components/schemas/AssetId'
              base64:
                $ref: '#/components/schemas/AssetBase64'
              url:
                $ref: '#/components/schemas/AssetUrl'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/AssetUrl'
            - $ref: '#/components/schemas/AssetId'
            - $ref: '#/components/schemas/AssetBase64'
          title: Asset
        fit:
          default: contain
          description: How the image fits the placeholder box
          enum:
            - cover
            - contain
            - crop
            - none
          title: Fit
          type: string
      required:
        - type
        - asset
      title: TemplateImageVariable
      type: object
    TemplateTextVariable:
      additionalProperties: false
      description: Replaces a text placeholder in the template.
      properties:
        type:
          const: text
          description: Variable type discriminator
          title: Type
          type: string
        content:
          description: >-
            Replacement text content. May be empty in GET responses (unfilled
            template default); must be non-empty when generating.
          maxLength: 10000
          title: Content
          type: string
      required:
        - type
        - content
      title: TemplateTextVariable
      type: object
    TemplateVideoVariable:
      additionalProperties: false
      description: Replaces a video placeholder in the template.
      properties:
        type:
          const: video
          description: Variable type discriminator
          title: Type
          type: string
        asset:
          description: Video to place. Accepts url, asset_id, or base64 input.
          discriminator:
            mapping:
              asset_id:
                $ref: '#/components/schemas/AssetId'
              base64:
                $ref: '#/components/schemas/AssetBase64'
              url:
                $ref: '#/components/schemas/AssetUrl'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/AssetUrl'
            - $ref: '#/components/schemas/AssetId'
            - $ref: '#/components/schemas/AssetBase64'
          title: Asset
        fit:
          default: contain
          description: How the video fits the placeholder box
          enum:
            - cover
            - contain
            - crop
            - none
          title: Fit
          type: string
        play_style:
          default: loop
          description: Playback behavior when the video is shorter than the scene
          enum:
            - fit_to_scene
            - freeze
            - loop
            - once
            - full_video
          title: Play Style
          type: string
        volume:
          default: 1
          description: Audio volume of the video track, 0.0 (muted) to 1.0
          maximum: 1
          minimum: 0
          title: Volume
          type: number
      required:
        - type
        - asset
      title: TemplateVideoVariable
      type: object
    TemplateVoiceVariable:
      additionalProperties: false
      description: Overrides the voice used by a script placeholder in the template.
      properties:
        type:
          const: voice
          description: Variable type discriminator
          title: Type
          type: string
        voice_id:
          description: Voice ID used for text-to-speech
          minLength: 1
          title: Voice Id
          type: string
        locale:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Optional voice locale, e.g. 'en-US'
          title: Locale
      required:
        - type
        - voice_id
      title: TemplateVoiceVariable
      type: object
    TemplateSceneV3:
      description: A scene defined in the template.
      properties:
        scene_id:
          description: Scene ID, usable in the generate request's scene_ids
          title: Scene Id
          type: string
        script:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Scene script text, with variable placeholders unreplaced
          title: Script
        variables:
          description: Variables used in this scene
          items:
            $ref: '#/components/schemas/TemplateSceneVariableRef'
          title: Variables
          type: array
      required:
        - scene_id
      title: TemplateSceneV3
      type: object
    AssetId:
      additionalProperties: false
      description: Asset input via HeyGen asset ID from the asset upload endpoint.
      properties:
        type:
          const: asset_id
          description: Input type discriminator
          title: Type
          type: string
        asset_id:
          description: HeyGen asset ID from the asset upload endpoint
          title: Asset Id
          type: string
      required:
        - type
        - asset_id
      title: AssetId
      type: object
    AssetBase64:
      additionalProperties: false
      description: Asset input via base64-encoded content.
      properties:
        type:
          const: base64
          description: Input type discriminator
          title: Type
          type: string
        media_type:
          description: MIME type of the encoded content (e.g. "image/png")
          title: Media Type
          type: string
        data:
          description: Base64-encoded file content
          title: Data
          type: string
      required:
        - type
        - media_type
        - data
      title: AssetBase64
      type: object
      x-mcp-visible: false
    AssetUrl:
      additionalProperties: false
      description: Asset input via publicly accessible HTTPS URL.
      properties:
        type:
          const: url
          description: Input type discriminator
          title: Type
          type: string
        url:
          description: Publicly accessible HTTPS URL for the asset
          title: Url
          type: string
      required:
        - type
        - url
      title: AssetUrl
      type: object
    TemplateSceneVariableRef:
      description: A variable used within a scene.
      properties:
        name:
          description: Variable name, matching a key in the template's variables
          title: Name
          type: string
        variable_type:
          description: 'Variable type: text, image, video, audio, character, or voice'
          title: Variable Type
          type: string
      required:
        - name
        - variable_type
      title: TemplateSceneVariableRef
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: HeyGen API key. Obtain from your HeyGen dashboard.
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth2 bearer token.

````