> ## 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.

# Update Template

> Renames a template. Other properties are edited in the HeyGen editor or through PUT /v3/templates/{template_id}/variables. Returns the template detail.



## OpenAPI

````yaml /openapi/external-api.json patch /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
    description: >-
      Create videos from a prompt or an avatar, then list, fetch, deliver and
      delete them
  - name: Avatar
    description: >-
      Create avatars and looks, record consent, and generate with the Avatar 6
      model
  - name: Voice
    description: Text to speech, speech to speech, and voice cloning
  - name: Audio
    description: Music, sound effects, transcription, stem separation and audio analysis
  - name: Image
    description: Generate images
  - name: Video editing
    description: >-
      Translate, lipsync, clip, analyze and remove filler words or backgrounds
      from existing videos
  - name: Video Agent
    description: Create videos from a prompt with an agent that plans, writes and edits
  - name: Templates
    description: Generate videos from reusable templates by replacing their variables
  - name: HyperFrames
    description: Render HyperFrames compositions into video
  - name: Brand
    description: >-
      Brand kits (colors, fonts, logos) and brand glossaries (term translations
      and pronunciations)
  - name: Assets and folders
    description: Upload files and organize them in folders
  - name: Batches
    description: Submit and track videos, translations, lipsyncs and uploads in bulk
  - name: Webhooks
    description: Manage webhook endpoints and events
  - name: Feedback
    description: Tell HeyGen how a generated result turned out
  - name: Account and usage
    description: Your account, the current API key, request logs and usage
paths:
  /v3/templates/{template_id}:
    patch:
      tags:
        - Templates
      summary: Update Template
      description: >-
        Renames a template. Other properties are edited in the HeyGen editor or
        through PUT /v3/templates/{template_id}/variables. Returns the template
        detail.
      operationId: updateTemplateV3
      parameters:
        - name: template_id
          in: path
          required: true
          schema:
            type: string
          description: Unique template identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTemplateV3Request'
      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: unauthorized
                  message: Invalid or expired API key. Verify your x-api-key header.
                  param: null
                  doc_url: null
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              example:
                error:
                  code: resource_access_denied
                  message: >-
                    Template creation is restricted by your workspace settings.
                    Ask a workspace admin to allow it.
                  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:
    UpdateTemplateV3Request:
      additionalProperties: false
      description: Request body for PATCH /v3/templates/{template_id}.
      properties:
        name:
          description: New template name
          examples:
            - Q4 outreach v2
          maxLength: 255
          minLength: 1
          title: Name
          type: string
      required:
        - name
      title: UpdateTemplateV3Request
      type: object
    TemplateDetailV3:
      description: >-
        Template detail: its variable schema, the July scene summary and, for
        authoring workspaces, its composition.
      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: '#/components/schemas/TemplateAudioVariable'
                character: '#/components/schemas/TemplateCharacterVariable'
                image: '#/components/schemas/TemplateImageVariable'
                text: '#/components/schemas/TemplateTextVariable'
                video: '#/components/schemas/TemplateVideoVariable'
                voice: '#/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
        source_video_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Video the template was created from, when known. Present only for
            workspaces with access to the template authoring API.
          title: Source Video Id
        edit_version:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Opaque version of the template returned by this request. Every save
            of the template's draft or variable set changes it, whether through
            PUT /v3/templates/{template_id}/variables or the HeyGen editor;
            renaming or deleting the template does not. Send it back as
            expected_edit_version on PUT /v3/templates/{template_id}/variables
            to detect concurrent edits. Present only for workspaces with access
            to the template authoring API.
          examples:
            - '3'
          title: Edit Version
        scene_ids:
          description: >-
            Scene IDs in template order, as POST /v3/templates/{template_id}
            accepts them
          items:
            type: string
          title: Scene Ids
          type: array
        scenes:
          deprecated: true
          description: >-
            Per-scene summary: the scene id, its script text and the variables
            it uses. Deprecated in favour of composition, which describes each
            scene in the same shape as GET /v3/videos/{video_id}/scenes; kept
            until a published sunset.
          items:
            $ref: '#/components/schemas/TemplateSceneV3'
          title: Scenes
          type: array
        composition:
          anyOf:
            - $ref: '#/components/schemas/TemplateComposition'
            - type: 'null'
          default: null
          description: >-
            The template's scenes and cross-scene audio tracks in the shape GET
            /v3/videos/{video_id}/scenes uses, with each node carrying the
            variable types it can be bound to (bindable_as), the variable bound
            to it (variable) and the text variables in its {{placeholders}}
            (text_variables). Present only for workspaces with access to the
            template authoring API, and omitted when the template's draft cannot
            be read.
      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
        errors:
          type: array
          description: >-
            Per-item error details for batch/multi-node failures (e.g. graph
            compilation errors by node).
          items:
            $ref: '#/components/schemas/StandardAPIErrorDetail'
        request_id:
          type: string
          description: >-
            Request identifier, also returned in the X-HeyGen-Request-Id
            response header. Include it when contacting support.
          example: 8c4f0b9e1d2a4f6b9e3c7a1d5f2b8e40
      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: '#/components/schemas/AssetId'
              base64: '#/components/schemas/AssetBase64'
              url: '#/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.


        The look is ``avatar_id``, the name every other v3 surface uses for it.
        Two older names for the

        same value were published before it and integrations were built against
        them, so both are still

        accepted on input and echoed on output, marked deprecated, until a
        published sunset. A client

        written against any edition of the docs keeps working.
      properties:
        type:
          const: character
          description: Variable type discriminator
          title: Type
          type: string
        avatar_id:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Avatar look ID to place; any avatar look, including talking photos.
            Same IDs as GET /v3/avatars/looks and as avatar_id on a scene's
            avatar element. Whether the look is an avatar or a talking photo is
            inferred from the look itself.
          examples:
            - Abigail_expressive_2024112501
          title: Avatar Id
        avatar_look_id:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          deprecated: true
          description: >-
            Deprecated alias of avatar_id. Accepted on input and returned with
            the same value; send avatar_id.
          title: Avatar Look Id
        character_id:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          deprecated: true
          description: >-
            Deprecated alias of avatar_id. Accepted on input and returned with
            the same value; send avatar_id.
          title: Character Id
        character_type:
          anyOf:
            - enum:
                - avatar
                - talking_photo
              type: string
            - type: 'null'
          default: null
          deprecated: true
          description: >-
            Deprecated. Ignored on input: whether the look is an avatar or a
            talking photo is inferred from the look itself. Returned as the kind
            recorded on the template.
          title: Character Type
      required:
        - type
      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: '#/components/schemas/AssetId'
              base64: '#/components/schemas/AssetBase64'
              url: '#/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 element's box. Omit it on a template created
            from a video with POST /v3/templates to keep that video's framing: a
            background fills the frame, a placed image fits inside its box. On a
            template built in the HeyGen editor the default is contain.
          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: '#/components/schemas/AssetId'
              base64: '#/components/schemas/AssetBase64'
              url: '#/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 element's box. Omit it on a template created
            from a video with POST /v3/templates to keep that video's framing: a
            background fills the frame, a placed clip fits inside its box. On a
            template built in the HeyGen editor the default is contain.
          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'. A region-qualified locale is
            stored in its canonical spelling ('en-us' becomes 'en-US'); any
            other value is stored as sent.
          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
    TemplateComposition:
      additionalProperties: false
      description: >-
        What the template is made of, in the vocabulary of GET
        /v3/videos/{video_id}/scenes.
      properties:
        scenes:
          description: >-
            Scenes in template order, each in the video-scenes shape plus
            bindings.
          items:
            $ref: '#/components/schemas/TemplateScene'
          title: Scenes
          type: array
        background_audio:
          description: >-
            Music and sound-effect tracks that play across scenes, with what an
            audio variable can replace.
          items:
            $ref: '#/components/schemas/TemplateBackgroundAudio'
          title: Background Audio
          type: array
      title: TemplateComposition
      type: object
    StandardAPIErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
          example: unknown_node_type
        message:
          type: string
          description: Human-readable error message
          example: Unknown node type
        node_id:
          type: string
          description: Graph node id this error pertains to, if applicable
        port:
          type: string
          description: Port name on the node this error pertains to, if applicable
        path:
          type: string
          description: Field path within the item this error pertains to, if applicable
      required:
        - code
        - message
    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 an asset upload or import; not a third-party
            file ID.
          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: >-
            Public http(s) URL HeyGen can download without auth or redirects.
            Not a local or sandbox path (/mnt/data/..., file://, sandbox:);
            upload such files and pass asset_id.
          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
    TemplateScene:
      additionalProperties: false
      description: >-
        One scene of the template, in template order, with what a variable can
        bind to in it.
      properties:
        id:
          description: Identifier of this scene within the video.
          title: Id
          type: string
        background:
          anyOf:
            - discriminator:
                mapping:
                  color: '#/components/schemas/ColorBackground'
                  image: '#/components/schemas/TemplateImageBackground'
                  video: '#/components/schemas/TemplateVideoBackground'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/ColorBackground'
                - $ref: '#/components/schemas/TemplateImageBackground'
                - $ref: '#/components/schemas/TemplateVideoBackground'
            - type: 'null'
          default: null
          description: What fills the frame behind this scene's elements.
          title: Background
        elements:
          description: Every element this scene places, in the template's own order.
          items:
            anyOf:
              - $ref: '#/components/schemas/TemplateAvatarElement'
              - $ref: '#/components/schemas/TemplateImageElement'
              - $ref: '#/components/schemas/TemplateVideoElement'
              - $ref: '#/components/schemas/TemplateTextElement'
              - $ref: '#/components/schemas/PlaceholderElement'
              - $ref: '#/components/schemas/TemplateContainerElement'
          title: Elements
          type: array
        script:
          description: >-
            This scene's audio sources in order, each one synthesized speech,
            uploaded audio, or a silence.
          items:
            anyOf:
              - $ref: '#/components/schemas/TemplateTextScriptEntry'
              - $ref: '#/components/schemas/TemplateAudioScriptEntry'
              - $ref: '#/components/schemas/SilenceScriptEntry'
          title: Script
          type: array
      required:
        - id
      title: TemplateScene
      type: object
    TemplateBackgroundAudio:
      additionalProperties: false
      description: >-
        A music or sound-effect track that plays across scenes; an audio
        variable replaces it.
      properties:
        bindable_as:
          description: Variable types that can be bound to this node.
          items:
            enum:
              - text
              - image
              - video
              - audio
              - character
              - voice
            type: string
          title: Bindable As
          type: array
        variable:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Name of the image, video, audio, character or voice variable bound
            to this node, if any.
          title: Variable
        text_variables:
          description: >-
            Text variable names appearing as {{placeholders}} in this node's
            text, in order of first appearance.
          items:
            type: string
          title: Text Variables
          type: array
        id:
          description: >-
            Opaque identifier of this track within the template. Stable for the
            life of the template.
          title: Id
          type: string
        type:
          const: audio
          default: audio
          description: Element type discriminator.
          title: Type
          type: string
        url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            URL of the track. Present when the template records a link and, if
            that link is signed, it is not at or near its deadline. Signed links
            expire, so download what you need rather than storing the URL.
          title: Url
      required:
        - id
      title: TemplateBackgroundAudio
      type: object
    ColorBackground:
      additionalProperties: false
      description: A solid colour filling the frame behind the scene's elements.
      properties:
        type:
          const: color
          default: color
          description: Background type discriminator.
          title: Type
          type: string
        color:
          description: Hex colour, e.g. '#f6f6fc'.
          title: Color
          type: string
      required:
        - color
      title: ColorBackground
      type: object
    TemplateImageBackground:
      additionalProperties: false
      description: A frame-filling image; an image variable replaces it.
      properties:
        id:
          description: >-
            Opaque identifier of this element within the video. Not to be
            parsed, sorted, or assumed to encode anything. Stable across edits
            and across regeneration of the video.
          title: Id
          type: string
        type:
          const: image
          default: image
          description: Background type discriminator.
          title: Type
          type: string
        url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            URL of the image. Present when the video records a link for this
            background and, if that link is signed, it is not at or near its
            deadline. Absent when no link is recorded, or the only recorded link
            has lapsed. Only the deadline is checked, so a present URL is not a
            promise that it resolves: it may name an object that has since
            moved, or a host the customer supplied. Signed links expire, so
            download what you need rather than storing the URL.
          title: Url
        bindable_as:
          description: Variable types that can be bound to this node.
          items:
            enum:
              - text
              - image
              - video
              - audio
              - character
              - voice
            type: string
          title: Bindable As
          type: array
        variable:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Name of the image, video, audio, character or voice variable bound
            to this node, if any.
          title: Variable
        text_variables:
          description: >-
            Text variable names appearing as {{placeholders}} in this node's
            text, in order of first appearance.
          items:
            type: string
          title: Text Variables
          type: array
      required:
        - id
      title: TemplateImageBackground
      type: object
    TemplateVideoBackground:
      additionalProperties: false
      description: A frame-filling clip; a video variable replaces it.
      properties:
        id:
          description: >-
            Opaque identifier of this element within the video. Not to be
            parsed, sorted, or assumed to encode anything. Stable across edits
            and across regeneration of the video.
          title: Id
          type: string
        type:
          const: video
          default: video
          description: Background type discriminator.
          title: Type
          type: string
        url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            URL of the clip. Present when the video records a link for this
            background and, if that link is signed, it is not at or near its
            deadline. Absent when no link is recorded, or the only recorded link
            has lapsed. Only the deadline is checked, so a present URL is not a
            promise that it resolves: it may name an object that has since
            moved, or a host the customer supplied. Signed links expire, so
            download what you need rather than storing the URL.
          title: Url
        playback:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            How the clip is reconciled to the scene. Same values as a video
            element's playback.
          title: Playback
        trim:
          anyOf:
            - $ref: '#/components/schemas/VideoTrim'
            - type: 'null'
          default: null
          description: Seconds trimmed from each end of the clip.
        volume:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Clip audio volume. 1.0 = source level, 0.0 = silent.
          title: Volume
        speed_multiplier:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Playback speed multiplier. 2.0 = twice as fast.
          title: Speed Multiplier
        bindable_as:
          description: Variable types that can be bound to this node.
          items:
            enum:
              - text
              - image
              - video
              - audio
              - character
              - voice
            type: string
          title: Bindable As
          type: array
        variable:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Name of the image, video, audio, character or voice variable bound
            to this node, if any.
          title: Variable
        text_variables:
          description: >-
            Text variable names appearing as {{placeholders}} in this node's
            text, in order of first appearance.
          items:
            type: string
          title: Text Variables
          type: array
      required:
        - id
      title: TemplateVideoBackground
      type: object
    TemplateAvatarElement:
      additionalProperties: false
      description: An avatar element; a character variable replaces its look.
      properties:
        id:
          description: >-
            Opaque identifier of this element within the video. Not to be
            parsed, sorted, or assumed to encode anything. Stable across edits
            and across regeneration of the video.
          title: Id
          type: string
        type:
          const: avatar
          default: avatar
          description: Element type discriminator.
          title: Type
          type: string
        avatar_id:
          description: The avatar look performing this scene.
          title: Avatar Id
          type: string
        engine:
          anyOf:
            - $ref: '#/components/schemas/AvatarEngineTier'
            - type: 'null'
          default: null
          description: >-
            Generation engine for this avatar. Absent when the video does not
            record one and none can be determined.
        expressiveness:
          anyOf:
            - $ref: '#/components/schemas/Expressiveness'
            - type: 'null'
          default: null
          description: Expressiveness level. Absent when left at the default.
        motion_prompt:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Motion description authored for this avatar.
          title: Motion Prompt
        bindable_as:
          description: Variable types that can be bound to this node.
          items:
            enum:
              - text
              - image
              - video
              - audio
              - character
              - voice
            type: string
          title: Bindable As
          type: array
        variable:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Name of the image, video, audio, character or voice variable bound
            to this node, if any.
          title: Variable
        text_variables:
          description: >-
            Text variable names appearing as {{placeholders}} in this node's
            text, in order of first appearance.
          items:
            type: string
          title: Text Variables
          type: array
      required:
        - id
        - avatar_id
      title: TemplateAvatarElement
      type: object
    TemplateImageElement:
      additionalProperties: false
      description: An image element; an image variable replaces its picture.
      properties:
        id:
          description: >-
            Opaque identifier of this element within the video. Not to be
            parsed, sorted, or assumed to encode anything. Stable across edits
            and across regeneration of the video.
          title: Id
          type: string
        type:
          const: image
          default: image
          description: Element type discriminator.
          title: Type
          type: string
        url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            URL of the image. Present when the video records a link for this
            element and, if that link is signed, it is not at or near its
            deadline. Absent when no link is recorded, or the only recorded link
            has lapsed; the element is still reported either way, so an image
            with no URL is one this read could not link to rather than an
            element this API does not describe. Only the deadline is checked, so
            a present URL is not a promise that it resolves: it may name an
            object that has since moved, or a host the customer supplied. Signed
            links expire, so download what you need rather than storing the URL.
          title: Url
        bindable_as:
          description: Variable types that can be bound to this node.
          items:
            enum:
              - text
              - image
              - video
              - audio
              - character
              - voice
            type: string
          title: Bindable As
          type: array
        variable:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Name of the image, video, audio, character or voice variable bound
            to this node, if any.
          title: Variable
        text_variables:
          description: >-
            Text variable names appearing as {{placeholders}} in this node's
            text, in order of first appearance.
          items:
            type: string
          title: Text Variables
          type: array
      required:
        - id
      title: TemplateImageElement
      type: object
    TemplateVideoElement:
      additionalProperties: false
      description: A video element; a video variable replaces its clip.
      properties:
        id:
          description: >-
            Opaque identifier of this element within the video. Not to be
            parsed, sorted, or assumed to encode anything. Stable across edits
            and across regeneration of the video.
          title: Id
          type: string
        type:
          const: video
          default: video
          description: Element type discriminator.
          title: Type
          type: string
        url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            URL of the clip. Present when the video records a link for this
            element and, if that link is signed, it is not at or near its
            deadline. Absent when no link is recorded, or the only recorded link
            has lapsed. Only the deadline is checked, so a present URL is not a
            promise that it resolves: it may name an object that has since
            moved, or a host the customer supplied. Signed links expire, so
            download what you need rather than storing the URL.
          title: Url
        playback:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            How the clip is reconciled to the scene: 'freeze' holds the last
            frame, 'loop' repeats it, 'fit_to_scene' changes speed to match,
            'full_video' plays it whole and drives the scene's length.
          title: Playback
        trim:
          anyOf:
            - $ref: '#/components/schemas/VideoTrim'
            - type: 'null'
          default: null
          description: Seconds trimmed from each end of the clip.
        volume:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Clip audio volume. 1.0 = source level, 0.0 = silent.
          title: Volume
        speed_multiplier:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Playback speed multiplier. 2.0 = twice as fast.
          title: Speed Multiplier
        bindable_as:
          description: Variable types that can be bound to this node.
          items:
            enum:
              - text
              - image
              - video
              - audio
              - character
              - voice
            type: string
          title: Bindable As
          type: array
        variable:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Name of the image, video, audio, character or voice variable bound
            to this node, if any.
          title: Variable
        text_variables:
          description: >-
            Text variable names appearing as {{placeholders}} in this node's
            text, in order of first appearance.
          items:
            type: string
          title: Text Variables
          type: array
      required:
        - id
      title: TemplateVideoElement
      type: object
    TemplateTextElement:
      additionalProperties: false
      description: An on-screen text element; text variables fill its {{placeholders}}.
      properties:
        id:
          description: >-
            Opaque identifier of this element within the video. Not to be
            parsed, sorted, or assumed to encode anything. Stable across edits
            and across regeneration of the video.
          title: Id
          type: string
        type:
          const: text
          default: text
          description: Element type discriminator.
          title: Type
          type: string
        text:
          description: >-
            The text as displayed. Paragraphs of styled text are joined with
            newlines.
          title: Text
          type: string
        bindable_as:
          description: Variable types that can be bound to this node.
          items:
            enum:
              - text
              - image
              - video
              - audio
              - character
              - voice
            type: string
          title: Bindable As
          type: array
        variable:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Name of the image, video, audio, character or voice variable bound
            to this node, if any.
          title: Variable
        text_variables:
          description: >-
            Text variable names appearing as {{placeholders}} in this node's
            text, in order of first appearance.
          items:
            type: string
          title: Text Variables
          type: array
      required:
        - id
        - text
      title: TemplateTextElement
      type: object
    PlaceholderElement:
      additionalProperties: false
      description: >-
        An element this version names but does not describe.


        Exists so a scene's ``elements`` array is never a filtered view
        presented as a complete one: a

        caller iterating it sees every element the scene places. Carries exactly
        two fields: which

        element this is, and what kind of thing it is.


        **Absence of content is not by itself proof that an element is
        undescribed.** A described

        category can serialize with nothing but an id and a type when every
        optional field happens to be

        unavailable, and one case is reachable today: an image with no usable
        link carries no ``url``,

        leaving ``{id, type}``. Read the ``type`` to tell them apart.

        ``avatar``, ``image``, ``video`` and ``text`` are described, so a bare
        one of those is a described

        element missing an optional value rather than an unexpanded node.


        The ``id`` matters most here. Two masked elements in one scene are
        otherwise identical on the

        wire, so without it a caller can see that the scene places two things
        and nothing else about

        either.
      properties:
        id:
          description: >-
            Opaque identifier of this element within the video. Not to be
            parsed, sorted, or assumed to encode anything. Stable across edits
            and across regeneration of the video.
          title: Id
          type: string
        type:
          description: >-
            The element's category. An **open set**: new values may be added, so
            treat an unrecognized one as an element to skip rather than an
            error. Several kinds of element can share one value, so a category
            says what an element is rather than naming a single underlying kind.
            Every value is permanent except 'other', which means 'a kind of
            element this API does not yet categorise' and may be replaced by a
            more specific category later.
          title: Type
          type: string
      required:
        - id
        - type
      title: PlaceholderElement
      type: object
    TemplateContainerElement:
      additionalProperties: false
      description: >-
        A group or mask; nothing binds to the container itself, its children
        carry their own bindings.
      properties:
        id:
          description: >-
            Opaque identifier of this element within the video. Not to be
            parsed, sorted, or assumed to encode anything. Stable across edits
            and across regeneration of the video.
          title: Id
          type: string
        type:
          description: The container's category, e.g. 'group' or 'mask'.
          title: Type
          type: string
        children:
          description: >-
            The elements this container holds, each described exactly as a
            top-level element would be.
          items:
            anyOf:
              - $ref: '#/components/schemas/TemplateAvatarElement'
              - $ref: '#/components/schemas/TemplateImageElement'
              - $ref: '#/components/schemas/TemplateVideoElement'
              - $ref: '#/components/schemas/TemplateTextElement'
              - $ref: '#/components/schemas/PlaceholderElement'
              - $ref: '#/components/schemas/TemplateContainerElement'
          title: Children
          type: array
      required:
        - id
        - type
      title: TemplateContainerElement
      type: object
    TemplateTextScriptEntry:
      additionalProperties: false
      description: >-
        Synthesized speech; a voice variable replaces its voice, text variables
        fill its {{placeholders}}.
      properties:
        id:
          description: >-
            Opaque identifier of this script entry within the video. Not to be
            parsed, sorted, or assumed to encode anything. The same id under two
            scenes means one entry is shared between them: its text belongs to
            both, and concatenating both scenes' scripts would synthesize the
            shared words twice.
          title: Id
          type: string
        type:
          const: text
          default: text
          description: Script entry type discriminator.
          title: Type
          type: string
        text:
          description: >-
            The script, verbatim, including inline markup. Empty when the scene
            was left unfinished.
          title: Text
          type: string
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: The voice delivering this script.
          title: Voice Id
        voice_settings:
          anyOf:
            - $ref: '#/components/schemas/ScriptVoiceSettings'
            - type: 'null'
          default: null
          description: Voice tuning applied to this script.
        trim_to_speech:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: >-
            Deprecated and ignored: the narration is kept whole, without
            trimming silence, whatever this says.
          title: Trim To Speech
        bindable_as:
          description: Variable types that can be bound to this node.
          items:
            enum:
              - text
              - image
              - video
              - audio
              - character
              - voice
            type: string
          title: Bindable As
          type: array
        variable:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Name of the image, video, audio, character or voice variable bound
            to this node, if any.
          title: Variable
        text_variables:
          description: >-
            Text variable names appearing as {{placeholders}} in this node's
            text, in order of first appearance.
          items:
            type: string
          title: Text Variables
          type: array
      required:
        - id
        - text
      title: TemplateTextScriptEntry
      type: object
    TemplateAudioScriptEntry:
      additionalProperties: false
      description: Uploaded audio; an audio variable replaces the recording.
      properties:
        id:
          description: Identifier of this script entry within the video.
          title: Id
          type: string
        type:
          const: audio
          default: audio
          description: Script entry type discriminator.
          title: Type
          type: string
        audio_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            URL of the audio. Present when the video records a link for this
            entry and, if that link is signed, it is not at or near its
            deadline. Absent when no link is recorded, or the only recorded link
            has lapsed. Only the deadline is checked, so a present URL is not a
            promise that it resolves: it may name an object that has since
            moved, or a host the customer supplied. Signed links expire, so
            download what you need rather than storing the URL.
          title: Audio Url
        bindable_as:
          description: Variable types that can be bound to this node.
          items:
            enum:
              - text
              - image
              - video
              - audio
              - character
              - voice
            type: string
          title: Bindable As
          type: array
        variable:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Name of the image, video, audio, character or voice variable bound
            to this node, if any.
          title: Variable
        text_variables:
          description: >-
            Text variable names appearing as {{placeholders}} in this node's
            text, in order of first appearance.
          items:
            type: string
          title: Text Variables
          type: array
      required:
        - id
      title: TemplateAudioScriptEntry
      type: object
    SilenceScriptEntry:
      additionalProperties: false
      description: A held silence, with no words spoken over the scene.
      properties:
        id:
          description: Identifier of this script entry within the video.
          title: Id
          type: string
        type:
          const: silence
          default: silence
          description: Script entry type discriminator.
          title: Type
          type: string
        duration:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: >-
            How long the silence is held, in seconds. Absent where the number
            does not describe what renders — on a scene whose video clip plays
            in full, the clip's own length governs the scene.
          title: Duration
      required:
        - id
      title: SilenceScriptEntry
      type: object
    VideoTrim:
      additionalProperties: false
      description: Seconds trimmed from each end of a clip.
      properties:
        start_offset:
          description: Seconds trimmed from the start of the clip.
          title: Start Offset
          type: number
        end_offset:
          description: Seconds trimmed from the end of the clip.
          title: End Offset
          type: number
      required:
        - start_offset
        - end_offset
      title: VideoTrim
      type: object
    AvatarEngineTier:
      description: Avatar engine selection.
      enum:
        - avatar_vi
        - heygen-avatar-6-turbo
        - avatar_v
        - avatar_iv
        - avatar_iii
      title: AvatarEngineTier
      type: string
    Expressiveness:
      description: Avatar expressiveness level for photo avatars.
      enum:
        - high
        - medium
        - low
      title: Expressiveness
      type: string
    ScriptVoiceSettings:
      additionalProperties: false
      description: >-
        The voice tuning applied to this script.


        A value here can fall outside the range the create API accepts, so
        validating it against a

        create request's schema will reject videos it should accept.
      properties:
        speed:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Playback speed multiplier.
          title: Speed
        pitch:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Pitch adjustment in semitones.
          title: Pitch
        volume:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: Voice audio volume. 1.0 = full, 0.0 = silent.
          title: Volume
        locale:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Locale/accent hint for multi-lingual voices (e.g. 'en-US').
          title: Locale
        engine_settings:
          anyOf:
            - discriminator:
                mapping:
                  cartesia: '#/components/schemas/CartesiaEngineSettings'
                  elevenlabs: '#/components/schemas/ElevenLabsEngineSettings'
                  fish: '#/components/schemas/FishEngineSettings'
                  heygen_voice: '#/components/schemas/HeyGenVoiceEngineSettings'
                  mockingbird: '#/components/schemas/MockingbirdEngineSettings'
                  orca: '#/components/schemas/HeyGenVoiceEngineSettings'
                  starfish: '#/components/schemas/StarfishEngineSettings'
                propertyName: engine_type
              oneOf:
                - $ref: '#/components/schemas/ElevenLabsEngineSettings'
                - $ref: '#/components/schemas/FishEngineSettings'
                - $ref: '#/components/schemas/StarfishEngineSettings'
                - $ref: '#/components/schemas/HeyGenVoiceEngineSettings'
                - $ref: '#/components/schemas/CartesiaEngineSettings'
                - $ref: '#/components/schemas/MockingbirdEngineSettings'
            - type: 'null'
          default: null
          description: >-
            The engine this line is set to use and its tuning, discriminated by
            'engine_type'. Present only when that engine is one of the six
            public voice engines; absent for any other engine or when the server
            picks one, except that a line carrying ElevenLabs tuning with no
            engine set reports elevenlabs.
          title: Engine Settings
      title: ScriptVoiceSettings
      type: object
    CartesiaEngineSettings:
      additionalProperties: false
      properties:
        engine_type:
          const: cartesia
          description: Select Cartesia.
          title: Engine Type
          type: string
        model:
          anyOf:
            - enum:
                - sonic-3.6
                - sonic-3.5
              type: string
            - type: 'null'
          default: null
          description: Cartesia Sonic model; omit for the engine default.
          title: Model
      required:
        - engine_type
      title: CartesiaEngineSettings
      type: object
    ElevenLabsEngineSettings:
      description: >-
        Engine-specific voice settings for ElevenLabs-backed voices.


        Supports model, stability, similarity_boost, style, and
        use_speaker_boost.

        When using eleven_v3 or eleven_v4, stability may be any value in [0.0,
        1.0].
      properties:
        model:
          anyOf:
            - enum:
                - eleven_multilingual_v2
                - eleven_turbo_v2_5
                - eleven_v3
                - eleven_v4
              type: string
            - type: 'null'
          default: null
          description: >-
            ElevenLabs model. eleven_v3 and eleven_v4 use stability only;
            similarity_boost, style, and use_speaker_boost have no effect on
            them.
          x-mcp-schema:
            anyOf:
              - type: string
              - type: 'null'
        similarity_boost:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          default: null
          description: The similarity boost parameter for ElevenLabs.
          title: Similarity Boost
        stability:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          default: null
          description: The stability parameter for ElevenLabs.
          title: Stability
        style:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          default: null
          description: The style parameter for ElevenLabs.
          title: Style
        use_speaker_boost:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: Whether to use speaker boost for ElevenLabs.
          title: Use Speaker Boost
        engine_type:
          const: elevenlabs
          description: >-
            Engine type discriminator. Must be 'elevenlabs' for
            ElevenLabs-backed voices.
          title: Engine Type
          type: string
      required:
        - engine_type
      title: ElevenLabsEngineSettings
      type: object
    FishEngineSettings:
      description: |-
        Engine-specific voice settings for Fish Audio-backed voices.

        Inherits Fish's tuning fields (model, stability, similarity).
      properties:
        model:
          anyOf:
            - enum:
                - s2.1-pro
                - s2-pro
              type: string
            - type: 'null'
          default: null
          description: Fish Audio model version. Defaults to s2.1-pro when omitted.
          x-mcp-schema:
            anyOf:
              - type: string
              - type: 'null'
        stability:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          default: null
          description: Stability parameter; higher is more consistent.
          title: Stability
        similarity:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          default: null
          description: Similarity parameter; how closely to match the source voice.
          title: Similarity
        engine_type:
          const: fish
          description: >-
            Engine type discriminator. Must be 'fish' for Fish Audio-backed
            voices.
          title: Engine Type
          type: string
      required:
        - engine_type
      title: FishEngineSettings
      type: object
    HeyGenVoiceEngineSettings:
      description: HeyGen Voice controls for instant or professional voice clones.
      properties:
        model:
          anyOf:
            - const: heygen-voice-1
              type: string
            - type: 'null'
          default: null
          description: >-
            HeyGen Voice model for instant voice clones. Defaults to
            heygen-voice-1. Ignored for professional voice clones.
          title: Model
        similarity:
          anyOf:
            - enum:
                - medium
                - high
                - extra_high
                - max
              type: string
            - type: 'null'
          default: null
          description: >-
            Similarity for instant voice clones. Ignored for professional voice
            clones.
          title: Similarity
        expressiveness:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          default: null
          description: Expressiveness from 0 to 1.
          title: Expressiveness
        pitch:
          anyOf:
            - maximum: 4
              minimum: -4
              multipleOf: 0.5
              type: number
            - type: 'null'
          default: null
          description: Pitch shift in semitones.
          title: Pitch
        inflection:
          anyOf:
            - maximum: 2
              minimum: 0.5
              type: number
            - type: 'null'
          default: null
          description: Pitch variation multiplier.
          title: Inflection
        engine_type:
          description: >-
            Engine type discriminator. 'heygen_voice' selects HeyGen Voice;
            'orca' is accepted as its legacy alias.
          enum:
            - heygen_voice
            - orca
          title: Engine Type
          type: string
      required:
        - engine_type
      title: HeyGenVoiceEngineSettings
      type: object
    MockingbirdEngineSettings:
      additionalProperties: false
      properties:
        engine_type:
          const: mockingbird
          description: Select Mockingbird. A regional voice_settings.locale is required.
          title: Engine Type
          type: string
      required:
        - engine_type
      title: MockingbirdEngineSettings
      type: object
    StarfishEngineSettings:
      description: >-
        Engine selection without tunable settings.


        Selects the engine named by ``engine_type`` on voices that support
        multiple engines.

        Send it in video creation requests to preserve the chosen engine.
      properties:
        engine_type:
          const: starfish
          description: Engine type discriminator for this settings variant.
          title: Engine Type
          type: string
      required:
        - engine_type
      title: StarfishEngineSettings
      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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.