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

# Create Video

> Creates an avatar video: a HeyGen avatar or an image speaks your script or audio with lip-sync. Choose Avatar III, IV, V or Avatar 6 (`heygen-avatar-6`, or `heygen-avatar-6-turbo` for faster renders) with `engine` (Avatar IV by default); a look's `supported_api_engines` lists the engines it supports. To generate a whole scene from a prompt instead, use POST /v3/models/videos.



## OpenAPI

````yaml /openapi/external-api.json post /v3/videos
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/videos:
    post:
      tags:
        - Video
      summary: Create Video
      description: >-
        Creates an avatar video: a HeyGen avatar or an image speaks your script
        or audio with lip-sync. Choose Avatar III, IV, V or Avatar 6
        (`heygen-avatar-6`, or `heygen-avatar-6-turbo` for faster renders) with
        `engine` (Avatar IV by default); a look's `supported_api_engines` lists
        the engines it supports. To generate a whole scene from a prompt
        instead, use POST /v3/models/videos.
      operationId: createVideo
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVideoV3RequestBody'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CreateVideoV3Response'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              examples:
                invalid_parameter:
                  summary: Invalid visual source
                  value:
                    error:
                      code: invalid_parameter
                      message: >-
                        Exactly one visual source required: avatar_id,
                        image_url, or image_asset_id.
                      param: avatar_id
                      doc_url: null
                avatar_not_usable:
                  summary: Avatar cannot be used
                  value:
                    error:
                      code: avatar_not_usable
                      message: >-
                        This avatar cannot be used because it did not pass
                        content moderation.
                      param: null
                      doc_url: null
        '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
        '409':
          description: >-
            Conflict — `error.code` is one of: `resource_not_ready`,
            `request_in_progress`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/StandardAPIError'
              examples:
                resource_not_ready:
                  summary: Avatar is still processing
                  value:
                    error:
                      code: resource_not_ready
                      message: >-
                        This avatar is still processing. Wait for avatar
                        creation to complete, then try again.
                      param: null
                      doc_url: null
                request_in_progress:
                  summary: Concurrent retry with same Idempotency-Key
                  value:
                    error:
                      code: request_in_progress
                      message: >-
                        A request with this Idempotency-Key is already in
                        progress. Retry shortly.
                      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:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        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.
      schema:
        type: string
        pattern: ^[A-Za-z0-9_\-:.]{1,255}$
        maxLength: 255
        minLength: 1
      example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    CreateVideoV3RequestBody:
      description: Discriminated union for POST /v3/videos request body.
      discriminator:
        mapping:
          avatar: '#/components/schemas/CreateVideoFromAvatar'
          cinematic_avatar: '#/components/schemas/CreateVideoFromCinematicAvatar'
          image: '#/components/schemas/CreateVideoFromImage'
          studio: '#/components/schemas/CreateVideoFromStudio'
        propertyName: type
      oneOf:
        - $ref: '#/components/schemas/CreateVideoFromAvatar'
        - $ref: '#/components/schemas/CreateVideoFromImage'
        - $ref: '#/components/schemas/CreateVideoFromCinematicAvatar'
        - $ref: '#/components/schemas/CreateVideoFromStudio'
      title: CreateVideoV3RequestBody
    CreateVideoV3Response:
      description: POST /v3/videos response.
      properties:
        video_id:
          description: Unique identifier for the created video.
          examples:
            - v_abc123def456
          title: Video Id
          type: string
        status:
          description: Initial video status (e.g. 'waiting').
          examples:
            - waiting
          title: Status
          type: string
        output_format:
          $ref: '#/components/schemas/VideoOutputFormat'
          default: mp4
          description: Resolved output format for the video.
        resolution:
          anyOf:
            - $ref: '#/components/schemas/VideoResolution'
            - type: 'null'
          default: null
          description: >-
            Resolution the video renders at. Null for Avatar VI; absent for
            cinematic avatar videos.
        resolution_note:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Set when the video renders at a lower resolution than requested
            because the account's plan caps it, worded to pass on to the user.
          title: Resolution Note
      required:
        - video_id
        - status
      title: CreateVideoV3Response
      type: object
      x-mcp-exclude-unset: true
    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
    CreateVideoFromAvatar:
      additionalProperties: false
      description: >-
        Create a video from a HeyGen avatar (video or photo avatar).


        Provide an avatar_id to use a previously created avatar. Supports all

        avatar types: studio_avatar, digital_twin, and photo_avatar. Optionally

        set ``engine`` to select Avatar V for eligible avatars; when omitted,
        the

        server defaults to Avatar IV.
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Display title for the video in the HeyGen dashboard.
          title: Title
        folder_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Destination folder ID in the caller's workspace, for example one
            returned by POST /v3/folders. Omit, pass null, or pass an empty
            string to place the result at the workspace root. The id must name a
            folder that is not in the trash and that the caller can write to.
            Assets library folders are accepted, but the HeyGen app files only
            assets in them, so a result placed there may not appear in the
            Assets library view. An unknown id, a folder in another workspace, a
            project of another kind such as a brand kit, or a trashed folder is
            rejected with 404 before anything is created. Supported only for
            single-video creation; batch video items cannot set their own
            destination folder.
          title: Folder Id
        resolution:
          anyOf:
            - $ref: '#/components/schemas/VideoResolution'
            - type: 'null'
          default: null
          description: >-
            Output video resolution. Defaults to 720p. `4k` is available for
            Avatar III digital twins and studio avatars. For apps signed in with
            OAuth, such as MCP clients, the account's plan sets the maximum:
            720p on Free, 1080p on Creator.
        aspect_ratio:
          anyOf:
            - $ref: '#/components/schemas/VideoAspectRatio'
            - type: 'null'
          default: '16:9'
          description: >-
            Output video aspect ratio. Supported values: '16:9', '9:16', '4:5',
            '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the
            source's aspect ratio (avatar source frames or uploaded image),
            short-edge anchored to the requested resolution and capped at the
            tier's long edge. Falls back to '16:9' when source dimensions can't
            be read.
          x-cli-default: auto
          x-mcp-default: auto
        fit:
          anyOf:
            - $ref: '#/components/schemas/AvatarFit'
            - type: 'null'
          default: null
          description: >-
            How the subject is fitted to the output canvas. 'cover' scales to
            fill the frame (may crop edges). 'contain' scales to fit entirely
            within the frame (may show background). When omitted, the server
            picks the best option based on the source and canvas orientations.
        background:
          anyOf:
            - $ref: '#/components/schemas/BackgroundSetting'
            - type: 'null'
          default: null
          description: Background settings for the video.
        remove_background:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: >-
            Remove the avatar background. Video avatars must be trained with
            matting enabled.
          title: Remove Background
        callback_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Webhook URL to receive a POST notification when the video is ready.
          title: Callback Url
        callback_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Caller-defined identifier echoed back in the webhook payload.
          title: Callback Id
        output_upload:
          anyOf:
            - $ref: '#/components/schemas/OutputUploadRequest'
            - type: 'null'
          default: null
          description: >-
            Upload the finished files straight into your own storage. Give a
            presigned PUT URL per file, for Amazon S3, Google Cloud Storage or
            Azure Blob Storage; HeyGen uploads each file when the video
            finishes. The outcome is reported by the video_delivery.success and
            video_delivery.fail webhooks. Available to enabled workspaces.
          x-cli-visible: false
          x-mcp-visible: false
        watermark:
          anyOf:
            - $ref: '#/components/schemas/WatermarkInput'
            - type: 'null'
          default: null
          description: >-
            Custom watermark image to overlay on the video (PNG or JPEG).
            Available to workspaces on an Enterprise web or API plan.
          x-cli-visible: false
          x-mcp-visible: false
        caption:
          anyOf:
            - $ref: '#/components/schemas/CaptionSetting'
            - type: 'null'
          default: null
          description: >-
            Caption generation settings. A sidecar subtitle file is always
            returned via subtitle_url; set 'style' to additionally burn captions
            into the rendered video.
        output_format:
          $ref: '#/components/schemas/VideoOutputFormat'
          default: mp4
          description: >-
            Output container. 'webm' returns a video with a transparent
            background (alpha channel); 'mp4' (default) returns a standard
            video. 'webm' requires an avatar that supports matting. When 'webm'
            is selected, any 'background' value is rejected and background
            removal is applied automatically — the caller does not need to set
            'remove_background'.
        script:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Text script for the avatar to speak. Pair with voice_id, or omit
            voice_id when using avatar_id to use the avatar's default voice.
            Mutually exclusive with audio_url/audio_asset_id.
          title: Script
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Voice ID for text-to-speech. Required when script is provided,
            unless avatar_id is set (the avatar's default voice is used as
            fallback).
          title: Voice Id
        audio_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Public http(s) URL of an audio file to lip-sync. Mutually exclusive
            with script. Not a local or sandbox path (/mnt/data/..., file://);
            upload it and pass audio_asset_id.
          title: Audio Url
        audio_asset_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            HeyGen asset ID of an uploaded audio file. Mutually exclusive with
            script.
          title: Audio Asset Id
        voice_settings:
          anyOf:
            - $ref: '#/components/schemas/VoiceSettingsInput'
            - type: 'null'
          default: null
          description: >-
            Voice settings. Always include engine_settings: the engine from GET
            /v3/videos/voice-capabilities, and a model only when that row lists
            models. locale is optional and is the accent only.
        type:
          const: avatar
          description: Must be 'avatar' for avatar-based video creation.
          title: Type
          type: string
        avatar_id:
          description: HeyGen avatar ID (video avatar or photo avatar look ID).
          title: Avatar Id
          type: string
        brand_glossary_id:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Brand glossary ID controlling how custom terms are pronounced in
            generated speech (for example, saying 'HeyGen' as 'hey-jen').
            Applies when the audio is synthesized from `script`; a
            caller-supplied `audio_url` or `audio_asset_id` is unaffected.
            Pronunciation is applied to the synthesized audio only, so caption
            and subtitle text still show the original script wording. Discover
            IDs via GET /v3/brand-glossaries.
          title: Brand Glossary Id
        motion_prompt:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Natural-language prompt controlling avatar body motion and hand
            gestures. Supported for photo avatars on either engine, and for
            video avatars when engine.type is 'avatar_v'. Rejected for video
            avatars on the default Avatar IV engine, and for photo avatars on
            'avatar_v' when the avatar's group has no animation reference (no
            digital twin or curated reference look).
          title: Motion Prompt
        expressiveness:
          anyOf:
            - $ref: '#/components/schemas/Expressiveness'
            - type: 'null'
          default: null
          description: >-
            Avatar expressiveness level. Photo avatars only. Defaults to 'low'
            when omitted. Avatar IV only; rejected when engine.type is
            'avatar_v'.
        engine:
          anyOf:
            - discriminator:
                mapping:
                  avatar_iii: '#/components/schemas/AvatarIIIEngineConfig'
                  avatar_iv: '#/components/schemas/AvatarIVEngineConfig'
                  avatar_v: '#/components/schemas/AvatarVEngineConfig'
                  heygen-avatar-6: '#/components/schemas/AvatarVIEngineConfig'
                  heygen-avatar-6-turbo: '#/components/schemas/AvatarVIEngineConfig'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/AvatarVEngineConfig'
                - $ref: '#/components/schemas/AvatarIVEngineConfig'
                - $ref: '#/components/schemas/AvatarIIIEngineConfig'
                - $ref: '#/components/schemas/AvatarVIEngineConfig'
            - type: 'null'
          default: null
          description: >-
            Engine configuration for video generation. Pass {"type": "avatar_v"}
            to enable cross-reference-driven animation for higher quality, or
            {"type": "heygen-avatar-6"} or {"type": "heygen-avatar-6-turbo"} for
            Avatar 6. Check supported_api_engines on the avatar look to confirm
            eligibility. Defaults to Avatar IV when omitted.
          title: Engine
      required:
        - type
        - avatar_id
      title: CreateVideoFromAvatar
      type: object
    CreateVideoFromCinematicAvatar:
      additionalProperties: false
      description: >-
        Create a video from a text prompt plus avatar and asset references
        (Cinematic Avatar).


        Cinematic Avatar generates a video from a natural-language ``prompt``
        guided by

        reference content: one to three avatar looks and optional reference
        assets

        (images / videos / audio). Unlike the ``avatar`` and ``image`` modes
        there is

        no script or voice — motion and speech are driven entirely by the prompt
        and

        the supplied references. The video model is chosen with ``model``.
      properties:
        type:
          const: cinematic_avatar
          description: Must be 'cinematic_avatar' for prompt-and-reference video creation.
          title: Type
          type: string
        prompt:
          description: Natural-language prompt describing the video to generate.
          maxLength: 10000
          minLength: 1
          title: Prompt
          type: string
        avatar_id:
          description: >-
            Avatar look ID(s) used as visual references. Provide 1 to 3 look
            IDs.
          items:
            type: string
          title: Avatar Id
          type: array
        model:
          anyOf:
            - $ref: '#/components/schemas/CinematicAvatarModel'
            - type: 'null'
          default: null
          description: >-
            Video model that renders the shot. Omitted means 'seedance_2'.
            'seedance_2' supports every aspect_ratio and resolution below.
            'heygen_video_1' renders 16:9 or 9:16 at 720p, 5–15 seconds long; it
            accepts each reference asset_id once.
        references:
          anyOf:
            - items:
                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'
              type: array
            - type: 'null'
          default: null
          description: >-
            Reference assets (images, videos, or audio) guiding the generation.
            Each accepts a URL, an asset_id, or inline base64. Combined limits:
            at most 3 videos and 9 images across avatars and references.
            'heygen_video_1' also accepts at most 3 audio clips (avatar voices
            included), 12 references in total, and 15 seconds of reference
            video, each avatar counting 3 seconds.
          title: References
        aspect_ratio:
          default: '16:9'
          description: >-
            Output aspect ratio. Supported for cinematic_avatar: '16:9', '9:16',
            '1:1' ('heygen_video_1': '16:9', '9:16'). Defaults to '16:9'.
          enum:
            - '16:9'
            - '9:16'
            - '1:1'
          title: Aspect Ratio
          type: string
        resolution:
          default: 720p
          description: >-
            Output resolution. Supported for cinematic_avatar: '720p', '1080p'
            ('heygen_video_1': '720p'). Defaults to '720p'.
          enum:
            - 720p
            - 1080p
          title: Resolution
          type: string
        auto_duration:
          default: false
          description: >-
            Renders the 10-second default with either model, the same as
            omitting duration. When true, omit duration.
          title: Auto Duration
          type: boolean
        duration:
          anyOf:
            - maximum: 15
              minimum: 4
              type: integer
            - type: 'null'
          default: null
          description: >-
            Video length in seconds (4–15; 5–15 for 'heygen_video_1'). Defaults
            to 10. Omit when auto_duration is true.
          title: Duration
        enhance_prompt:
          default: false
          description: Enable server-side prompt enhancement.
          title: Enhance Prompt
          type: boolean
        title:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Display title for the video in the HeyGen dashboard.
          title: Title
        folder_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Destination folder ID in the caller's workspace, for example one
            returned by POST /v3/folders. Omit, pass null, or pass an empty
            string to place the result at the workspace root. The id must name a
            folder that is not in the trash and that the caller can write to.
            Assets library folders are accepted, but the HeyGen app files only
            assets in them, so a result placed there may not appear in the
            Assets library view. An unknown id, a folder in another workspace, a
            project of another kind such as a brand kit, or a trashed folder is
            rejected with 404 before anything is created. Supported only for
            single-video creation; batch video items cannot set their own
            destination folder.
          title: Folder Id
      required:
        - type
        - prompt
        - avatar_id
      title: CreateVideoFromCinematicAvatar
      type: object
    CreateVideoFromImage:
      additionalProperties: false
      description: >-
        Create a lip-synced video from an image of a person.


        The image must show a clearly visible, human-like face: a photo, or a
        realistic

        illustration of a person. Images without a detectable face are rejected
        with 400.

        For non-human or stylized characters (mascots, animals, objects), use
        the

        image_to_video or reference_to_video mode of POST /v3/models/videos
        instead.


        Provide an image via URL, asset ID, or inline base64. The image will be

        animated with lip-sync to the provided audio or generated speech.
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Display title for the video in the HeyGen dashboard.
          title: Title
        folder_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Destination folder ID in the caller's workspace, for example one
            returned by POST /v3/folders. Omit, pass null, or pass an empty
            string to place the result at the workspace root. The id must name a
            folder that is not in the trash and that the caller can write to.
            Assets library folders are accepted, but the HeyGen app files only
            assets in them, so a result placed there may not appear in the
            Assets library view. An unknown id, a folder in another workspace, a
            project of another kind such as a brand kit, or a trashed folder is
            rejected with 404 before anything is created. Supported only for
            single-video creation; batch video items cannot set their own
            destination folder.
          title: Folder Id
        resolution:
          anyOf:
            - $ref: '#/components/schemas/VideoResolution'
            - type: 'null'
          default: null
          description: >-
            Output video resolution. Defaults to 720p. `4k` is available for
            Avatar III digital twins and studio avatars. For apps signed in with
            OAuth, such as MCP clients, the account's plan sets the maximum:
            720p on Free, 1080p on Creator.
        aspect_ratio:
          anyOf:
            - $ref: '#/components/schemas/VideoAspectRatio'
            - type: 'null'
          default: '16:9'
          description: >-
            Output video aspect ratio. Supported values: '16:9', '9:16', '4:5',
            '5:4', '1:1', 'auto'. Defaults to '16:9'. 'auto' preserves the
            source's aspect ratio (avatar source frames or uploaded image),
            short-edge anchored to the requested resolution and capped at the
            tier's long edge. Falls back to '16:9' when source dimensions can't
            be read.
          x-cli-default: auto
          x-mcp-default: auto
        fit:
          anyOf:
            - $ref: '#/components/schemas/AvatarFit'
            - type: 'null'
          default: null
          description: >-
            How the subject is fitted to the output canvas. 'cover' scales to
            fill the frame (may crop edges). 'contain' scales to fit entirely
            within the frame (may show background). When omitted, the server
            picks the best option based on the source and canvas orientations.
        background:
          anyOf:
            - $ref: '#/components/schemas/BackgroundSetting'
            - type: 'null'
          default: null
          description: Background settings for the video.
        remove_background:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: >-
            Remove the avatar background. Video avatars must be trained with
            matting enabled.
          title: Remove Background
        callback_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Webhook URL to receive a POST notification when the video is ready.
          title: Callback Url
        callback_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Caller-defined identifier echoed back in the webhook payload.
          title: Callback Id
        output_upload:
          anyOf:
            - $ref: '#/components/schemas/OutputUploadRequest'
            - type: 'null'
          default: null
          description: >-
            Upload the finished files straight into your own storage. Give a
            presigned PUT URL per file, for Amazon S3, Google Cloud Storage or
            Azure Blob Storage; HeyGen uploads each file when the video
            finishes. The outcome is reported by the video_delivery.success and
            video_delivery.fail webhooks. Available to enabled workspaces.
          x-cli-visible: false
          x-mcp-visible: false
        watermark:
          anyOf:
            - $ref: '#/components/schemas/WatermarkInput'
            - type: 'null'
          default: null
          description: >-
            Custom watermark image to overlay on the video (PNG or JPEG).
            Available to workspaces on an Enterprise web or API plan.
          x-cli-visible: false
          x-mcp-visible: false
        caption:
          anyOf:
            - $ref: '#/components/schemas/CaptionSetting'
            - type: 'null'
          default: null
          description: >-
            Caption generation settings. A sidecar subtitle file is always
            returned via subtitle_url; set 'style' to additionally burn captions
            into the rendered video.
        output_format:
          $ref: '#/components/schemas/VideoOutputFormat'
          default: mp4
          description: >-
            Output container. 'webm' returns a video with a transparent
            background (alpha channel); 'mp4' (default) returns a standard
            video. 'webm' requires an avatar that supports matting. When 'webm'
            is selected, any 'background' value is rejected and background
            removal is applied automatically — the caller does not need to set
            'remove_background'.
        script:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Text script for the avatar to speak. Pair with voice_id, or omit
            voice_id when using avatar_id to use the avatar's default voice.
            Mutually exclusive with audio_url/audio_asset_id.
          title: Script
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Voice ID for text-to-speech. Required when script is provided,
            unless avatar_id is set (the avatar's default voice is used as
            fallback).
          title: Voice Id
        audio_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Public http(s) URL of an audio file to lip-sync. Mutually exclusive
            with script. Not a local or sandbox path (/mnt/data/..., file://);
            upload it and pass audio_asset_id.
          title: Audio Url
        audio_asset_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            HeyGen asset ID of an uploaded audio file. Mutually exclusive with
            script.
          title: Audio Asset Id
        voice_settings:
          anyOf:
            - $ref: '#/components/schemas/VoiceSettingsInput'
            - type: 'null'
          default: null
          description: >-
            Voice settings. Always include engine_settings: the engine from GET
            /v3/videos/voice-capabilities, and a model only when that row lists
            models. locale is optional and is the accent only.
        type:
          const: image
          description: Must be 'image' for image-based video creation.
          title: Type
          type: string
        image:
          description: Image to animate. Accepts URL, asset ID, or base64-encoded data.
          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: Image
        brand_glossary_id:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Brand glossary ID controlling how custom terms are pronounced in
            generated speech (for example, saying 'HeyGen' as 'hey-jen').
            Applies when the audio is synthesized from `script`; a
            caller-supplied `audio_url` or `audio_asset_id` is unaffected.
            Pronunciation is applied to the synthesized audio only, so caption
            and subtitle text still show the original script wording. Discover
            IDs via GET /v3/brand-glossaries.
          title: Brand Glossary Id
        motion_prompt:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Natural-language prompt controlling avatar body motion. Photo
            avatars only.
          title: Motion Prompt
        expressiveness:
          anyOf:
            - $ref: '#/components/schemas/Expressiveness'
            - type: 'null'
          default: null
          description: >-
            Avatar expressiveness level. Photo avatars only. Defaults to 'low'
            when omitted.
        engine:
          anyOf:
            - discriminator:
                mapping:
                  avatar_iv: '#/components/schemas/AvatarIVEngineConfig'
                  heygen-avatar-6: '#/components/schemas/AvatarVIEngineConfig'
                  heygen-avatar-6-turbo: '#/components/schemas/AvatarVIEngineConfig'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/AvatarIVEngineConfig'
                - $ref: '#/components/schemas/AvatarVIEngineConfig'
            - type: 'null'
          default: null
          description: >-
            Engine that animates the image. Omit for Avatar IV. Avatar 6 renders
            straight from the image (no motion reference), so its
            reference_look_id is not accepted here.
          title: Engine
      required:
        - type
        - image
      title: CreateVideoFromImage
      type: object
    CreateVideoFromStudio:
      additionalProperties: false
      description: >-
        Create a single video by composing an ordered list of whole-frame
        scenes.


        The server owns layout and center-crops each scene to the global output

        canvas. Output settings are global (one per request); a single video_id
        is

        returned and rendering is all-or-nothing. MP4 only in v1 — the output

        container is fixed and ``output_format`` is not exposed.
      properties:
        type:
          const: studio
          description: Must be 'studio' for scene-composition video creation.
          title: Type
          type: string
        title:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Display title for the video in the HeyGen dashboard.
          title: Title
        folder_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Destination folder ID in the caller's workspace, for example one
            returned by POST /v3/folders. Omit, pass null, or pass an empty
            string to place the result at the workspace root. The id must name a
            folder that is not in the trash and that the caller can write to.
            Assets library folders are accepted, but the HeyGen app files only
            assets in them, so a result placed there may not appear in the
            Assets library view. An unknown id, a folder in another workspace, a
            project of another kind such as a brand kit, or a trashed folder is
            rejected with 404 before anything is created. Supported only for
            single-video creation; batch video items cannot set their own
            destination folder.
          title: Folder Id
        aspect_ratio:
          anyOf:
            - $ref: '#/components/schemas/VideoAspectRatio'
            - type: 'null'
          default: '16:9'
          description: >-
            Global output aspect ratio. Supported values: '16:9', '9:16', '4:5',
            '5:4', '1:1', 'auto'. Defaults to '16:9'. Each scene is
            center-cropped to this canvas.
          x-cli-default: auto
          x-mcp-default: auto
        resolution:
          anyOf:
            - $ref: '#/components/schemas/VideoResolution'
            - type: 'null'
          default: null
          description: >-
            Global output video resolution. Defaults to 1080p. `4k` is available
            for Avatar III digital twins and studio avatars. For apps signed in
            with OAuth, such as MCP clients, the account's plan sets the
            maximum: 720p on Free, 1080p on Creator.
        brand_glossary_id:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Brand glossary ID controlling how custom terms are pronounced in
            generated speech (for example, saying 'HeyGen' as 'hey-jen').
            Applies to every scene whose audio is synthesized from a script;
            scenes that supply their own audio URL or audio asset are
            unaffected. Pronunciation is applied to the synthesized audio only,
            so caption and subtitle text still show the original script wording.
            Discover IDs via GET /v3/brand-glossaries.
          title: Brand Glossary Id
        callback_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Webhook URL to receive a POST notification when the video is ready.
          title: Callback Url
        callback_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Caller-defined identifier echoed back in the webhook payload.
          title: Callback Id
        caption:
          anyOf:
            - $ref: '#/components/schemas/CaptionSetting'
            - type: 'null'
          default: null
          description: >-
            Caption generation settings. A sidecar subtitle file is always
            returned via subtitle_url; set 'style' to additionally burn captions
            into the rendered video.
        watermark:
          anyOf:
            - $ref: '#/components/schemas/WatermarkInput'
            - type: 'null'
          default: null
          description: >-
            Custom watermark image to overlay on the video (PNG or JPEG).
            Available to workspaces on an Enterprise web or API plan.
          x-cli-visible: false
          x-mcp-visible: false
        scenes:
          description: >-
            Ordered list of whole-frame scenes to concatenate. Each scene is one
            of 'avatar_video', 'image', or 'video'. Must contain 1 to 50 scenes.
          items:
            discriminator:
              mapping:
                avatar_video: '#/components/schemas/AvatarVideoScene'
                image: '#/components/schemas/ImageScene'
                video: '#/components/schemas/VideoScene'
              propertyName: type
            oneOf:
              - $ref: '#/components/schemas/AvatarVideoScene'
              - $ref: '#/components/schemas/ImageScene'
              - $ref: '#/components/schemas/VideoScene'
          title: Scenes
          type: array
      required:
        - type
        - scenes
      title: CreateVideoFromStudio
      type: object
    VideoOutputFormat:
      description: Output container for the generated video.
      enum:
        - mp4
        - webm
      title: VideoOutputFormat
      type: string
    VideoResolution:
      description: |-
        Output video resolution.

        `4k` is available for Avatar III digital twins and studio avatars.
      enum:
        - 4k
        - 1080p
        - 720p
      title: VideoResolution
      type: string
    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
    VideoAspectRatio:
      description: >-
        Output video aspect ratio.


        - ``16:9`` / ``9:16``: classic landscape / portrait.

        - ``4:5`` / ``5:4`` / ``1:1``: social-media-friendly ratios. Output is
        short-edge anchored to
          the requested resolution (e.g. ``1080p`` 1:1 → 1080x1080, ``1080p`` 4:5 → 1080x1350).
        - ``auto``: preserve the source's aspect ratio. The dimensions are
        derived from the avatar's
          source frames (``avatar_id``) or the uploaded image (``image_url`` / ``image_asset_id``),
          short-edge anchored to the requested resolution and capped at the tier's long edge.
          Falls back to ``16:9`` when source dimensions can't be read.
      enum:
        - '16:9'
        - '9:16'
        - '4:5'
        - '5:4'
        - '1:1'
        - auto
      title: VideoAspectRatio
      type: string
    AvatarFit:
      description: How the avatar is scaled to the output canvas.
      enum:
        - contain
        - cover
      title: AvatarFit
      type: string
    BackgroundSetting:
      description: Background configuration for the generated video.
      properties:
        type:
          description: >-
            Background type. 'color' uses a solid hex color; 'image' uses an
            image from url or asset_id.
          enum:
            - color
            - image
          title: Type
          type: string
        value:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Hex color code (e.g. '#ff0000'). Required when type is 'color'.
          title: Value
        url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            URL of the background image. Used when type is 'image'. Mutually
            exclusive with asset_id.
          title: Url
        asset_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            HeyGen asset ID of the background image. Used when type is 'image'.
            Mutually exclusive with url.
          title: Asset Id
      required:
        - type
      title: BackgroundSetting
      type: object
    OutputUploadRequest:
      additionalProperties: false
      description: Where the finished files go. Each file needs its own URL.
      properties:
        video:
          $ref: '#/components/schemas/UploadTargetRequest'
          description: Upload target for the finished video file.
        captions:
          anyOf:
            - $ref: '#/components/schemas/UploadTargetRequest'
            - type: 'null'
          default: null
          description: Upload target for the caption file, when the video has captions.
        thumbnail:
          anyOf:
            - $ref: '#/components/schemas/UploadTargetRequest'
            - type: 'null'
          default: null
          description: Upload target for the thumbnail image.
      required:
        - video
      title: OutputUploadRequest
      type: object
    WatermarkInput:
      additionalProperties: false
      description: Watermark configuration for video creation.
      properties:
        image:
          description: Image asset to use as the watermark overlay (PNG or JPEG).
          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: Image
        scale:
          default: 1
          description: >-
            Scale multiplier for the watermark image. 1.0 renders at native
            size.
          exclusiveMinimum: 0
          maximum: 2
          title: Scale
          type: number
        opacity:
          default: 1
          description: Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.
          maximum: 1
          minimum: 0
          title: Opacity
          type: number
        placement:
          anyOf:
            - $ref: '#/components/schemas/WatermarkPlacement'
            - type: 'null'
          default: null
          description: >-
            Watermark placement. Defaults to bottom-right with standard margins
            when omitted.
      required:
        - image
      title: WatermarkInput
      type: object
    CaptionSetting:
      description: >-
        Caption generation settings for video creation.


        A sidecar subtitle file is always generated and returned via
        ``subtitle_url``

        in the chosen ``file_format``. When ``style`` is also set, captions are

        additionally burned into the rendered video — the sidecar is still
        delivered.
      properties:
        file_format:
          $ref: '#/components/schemas/CaptionFileFormat'
          default: srt
          description: Output format for the sidecar caption file.
        style:
          anyOf:
            - $ref: '#/components/schemas/CaptionStyle'
            - type: 'null'
          default: null
          description: >-
            Visual style for burning captions into the rendered video. Omit for
            sidecar-only captions.
      title: CaptionSetting
      type: object
    VoiceSettingsInput:
      description: >-
        Voice tuning parameters for text-to-speech.


        Applies to a `script` spoken using `voice_id` or an avatar's default
        voice.

        It does not apply to `audio_url` or `audio_asset_id` (supplied audio
        bypasses TTS).
      properties:
        speed:
          default: 1
          description: Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).
          maximum: 1.5
          minimum: 0.5
          title: Speed
          type: number
        pitch:
          default: 0
          description: >-
            Legacy pitch adjustment, normalized to -1 to 1 before synthesis.
            Among the six documented engines, only Mockingbird can apply it when
            its base TTS uses Azure; use engine_settings.pitch for HeyGen Voice.
          maximum: 50
          minimum: -50
          title: Pitch
          type: number
        volume:
          default: 1
          description: >-
            Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing
            spoken voice with background audio.
          maximum: 1
          minimum: 0
          title: Volume
          type: number
        locale:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Accent the user asked for (e.g. 'en-US'). It is not the script
            language; the language is read from the script. Omit for Original
            Accent, the voice's natural accent. Send only a locale that GET
            /v3/videos/voice-capabilities lists for the script's language and
            the engine in engine_settings. Mockingbird requires a regional
            locale.
          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: >-
            Engine-specific voice tuning, discriminated by 'engine_type'. Always
            name the engine and, where offered, its model so the request
            reflects the selected voice and model. The request is rejected if
            the voice_id is not compatible with the selected engine. Always send
            it. A request without it gets its engine at render time and can fail
            after the video is created.
          title: Engine Settings
      title: VoiceSettingsInput
      type: object
    Expressiveness:
      description: Avatar expressiveness level for photo avatars.
      enum:
        - high
        - medium
        - low
      title: Expressiveness
      type: string
    AvatarIIIEngineConfig:
      additionalProperties: false
      description: >-
        Avatar III engine configuration.


        A single engine value that resolves to the right product by the avatar's

        look type (mirrors how ``avatar_iv`` already serves both photo and video

        avatars):


        - video avatar looks (``digital_twin``, ``studio_avatar``) -> Digital
        Twin
          (supports 4K)
        - ``photo_avatar`` look -> Photo Avatar (no 4K output)


        Not supported for raw image input (``type: "image"``).

        ``motion_prompt`` and ``expressiveness`` are not supported with this
        engine.
      properties:
        type:
          const: avatar_iii
          description: >-
            Engine type discriminator. Must be 'avatar_iii'. Resolves to Digital
            Twin for video avatar looks (digital_twin, studio_avatar) and Photo
            Avatar for photo_avatar looks; not supported for raw image input.
            Check supported_api_engines on the avatar look to confirm
            eligibility.
          title: Type
          type: string
      required:
        - type
      title: AvatarIIIEngineConfig
      type: object
    AvatarIVEngineConfig:
      additionalProperties: false
      description: Avatar IV engine configuration (default behavior).
      properties:
        type:
          const: avatar_iv
          description: Engine type discriminator. Must be 'avatar_iv'.
          title: Type
          type: string
      required:
        - type
      title: AvatarIVEngineConfig
      type: object
    AvatarVEngineConfig:
      additionalProperties: false
      description: Avatar V engine configuration with cross-reference-driven animation.
      properties:
        type:
          const: avatar_v
          description: >-
            Engine type discriminator. Must be 'avatar_v'. Check
            supported_api_engines on the avatar look to confirm eligibility.
          title: Type
          type: string
        reference_look_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Optional look to use as the animation reference. When provided, it
            must be a `digital_twin` look accessible to your workspace and in
            the same avatar group as `avatar_id` (`studio_avatar` and
            `photo_avatar` looks are rejected). When omitted, video avatars
            self-reference and photo avatars select from their group's eligible
            candidates, preferring digital twins (ready first, then processing /
            upgrading), then curated public studio looks. A photo avatar whose
            group has no eligible reference renders directly from its image
            without one; motion_prompt is rejected in that case. A non-public
            `digital_twin` reference, whether provided or selected
            automatically, must also satisfy its group's consent requirements.
          title: Reference Look Id
        more_blinking:
          default: false
          description: Ask Avatar V for more natural blinking.
          title: More Blinking
          type: boolean
      required:
        - type
      title: AvatarVEngineConfig
      type: object
    AvatarVIEngineConfig:
      additionalProperties: false
      description: >-
        Avatar 6 engine. Renders at 1080p by default; set resolution to `2k` for
        2K, which only Avatar 6 renders. Check

        supported_api_engines on the avatar look to confirm eligibility.
      properties:
        type:
          description: >-
            Engine type discriminator. 'heygen-avatar-6', or
            'heygen-avatar-6-turbo' for faster, lower-cost renders.
          enum:
            - heygen-avatar-6
            - heygen-avatar-6-turbo
          title: Type
          type: string
        motion_expressiveness:
          default: default
          description: >-
            Use default for the model's usual motion, or less for fewer and
            smaller gestures and calmer facial expressions. Does not disable
            motion. motion_prompt overrides this where specified.
          enum:
            - default
            - less
          title: Motion Expressiveness
          type: string
        reference_look_id:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Optional digital_twin look to use as the motion reference. Must be
            accessible to your workspace, belong to the same avatar group as
            avatar_id, and satisfy consent requirements. When omitted, video
            looks use their own footage and photo looks render without a video
            reference.
          title: Reference Look Id
      required:
        - type
      title: AvatarVIEngineConfig
      type: object
    CinematicAvatarModel:
      description: Video model that renders a Cinematic Avatar shot.
      enum:
        - seedance_2
        - heygen_video_1
      title: CinematicAvatarModel
      type: string
    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
    AvatarVideoScene:
      additionalProperties: false
      description: A whole-frame speaking scene backed by an avatar.
      properties:
        type:
          const: avatar_video
          description: Must be 'avatar_video' for an avatar speaking scene.
          title: Type
          type: string
        input:
          $ref: '#/components/schemas/StudioAvatarInput'
          description: >-
            Scene source ('type': 'avatar'): an avatar_id plus one audio source.
            The avatar_id accepts any avatar look — video avatars and photo
            avatars alike (pass a photo avatar's look id to get a talking
            photo). The scene duration is derived server-side from the audio.
      required:
        - type
        - input
      title: AvatarVideoScene
      type: object
    ImageScene:
      additionalProperties: false
      description: >-
        A whole-frame still-image scene: either silent (held for ``duration``)
        or narrated.


        Exactly one mode must be chosen:

        - silent: set ``duration`` (seconds) and no audio source.

        - narrated: set exactly one audio source (script + voice_id, audio_url,
        or
          audio_asset_id) and omit ``duration`` — the scene length follows the audio.
      properties:
        type:
          const: image
          description: Must be 'image' for a still-image scene.
          title: Type
          type: string
        source:
          description: >-
            Still image to display. Accepts URL, asset ID, or base64-encoded
            data.
          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: Source
        duration:
          anyOf:
            - exclusiveMinimum: 0
              maximum: 300
              type: number
            - type: 'null'
          default: null
          description: >-
            Silent mode: hold the still image for this many seconds. Mutually
            exclusive with any audio source. Must be > 0 and <= 300.
          title: Duration
        script:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Narrated mode: text to speak over the image. Pair with voice_id.
            Mutually exclusive with duration/audio_url/audio_asset_id.
          title: Script
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Voice ID for text-to-speech. Required when script is provided.
          title: Voice Id
        audio_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Narrated mode: public http(s) URL of an audio file to play over the
            image. Mutually exclusive with duration/script. Not a local or
            sandbox path (/mnt/data/..., file://); upload it and pass
            audio_asset_id.
          title: Audio Url
        audio_asset_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually
            exclusive with duration/script.
          title: Audio Asset Id
        voice_settings:
          anyOf:
            - $ref: '#/components/schemas/VoiceSettingsInput'
            - type: 'null'
          default: null
          description: >-
            Voice settings. Always include engine_settings: the engine from GET
            /v3/videos/voice-capabilities, and a model only when that row lists
            models. locale is optional and is the accent only.
      required:
        - type
        - source
      title: ImageScene
      type: object
    VideoScene:
      additionalProperties: false
      description: >-
        A whole-frame scene backed by an existing video clip.


        Optional ``playback`` exposes the audio volume / mute capability; when

        omitted the clip plays at its source volume.


        For optional voiceover / narration, supply at most one audio source

        (``script`` + ``voice_id``, ``audio_url``, or ``audio_asset_id``) — the
        *same*

        audio inputs a narrated ``image`` scene accepts. When present, the
        narration

        drives the scene length and ``playback.mode`` controls whether the clip

        freezes, loops, or changes speed to fit that duration. When omitted the
        clip

        plays full-length as before. The clip's own audio level is still
        governed by

        ``playback`` (the two compose).
      properties:
        type:
          const: video
          description: Must be 'video' for a video-clip scene.
          title: Type
          type: string
        source:
          description: >-
            Video clip to include. Accepts URL, asset ID, or base64-encoded
            data.
          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: Source
        playback:
          anyOf:
            - $ref: '#/components/schemas/PlaybackInput'
            - type: 'null'
          default: null
          description: >-
            Optional playback capability: narrated-clip alignment 'mode', audio
            'volume' (0.0–1.0), and 'mute'. Omit to use freeze alignment and
            keep the clip's source volume.
        script:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Optional voiceover: text to speak over the clip. Pair with voice_id.
            Mutually exclusive with audio_url/audio_asset_id.
          title: Script
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Voice ID for text-to-speech. Required when script is provided.
          title: Voice Id
        audio_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Optional voiceover: public http(s) URL of an audio file to play over
            the clip. Mutually exclusive with script/audio_asset_id. Not a local
            or sandbox path (/mnt/data/..., file://); upload it and pass
            audio_asset_id.
          title: Audio Url
        audio_asset_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Optional voiceover: HeyGen asset ID of an uploaded audio file.
            Mutually exclusive with script/audio_url.
          title: Audio Asset Id
        voice_settings:
          anyOf:
            - $ref: '#/components/schemas/VoiceSettingsInput'
            - type: 'null'
          default: null
          description: >-
            Voice settings for a script voiceover. Always include
            engine_settings: the engine from GET /v3/videos/voice-capabilities,
            and a model only when that row lists models. locale is optional and
            is the accent only.
      required:
        - type
        - source
      title: VideoScene
      type: object
    UploadTargetRequest:
      additionalProperties: false
      properties:
        url:
          description: >-
            A presigned PUT URL for Amazon S3, Google Cloud Storage or Azure
            Blob Storage, signed for the object key this file should land at. It
            must stay valid for at least one hour; 24 hours or more is
            recommended, because the file is uploaded when the video finishes.
          maxLength: 4096
          title: Url
          type: string
        headers:
          additionalProperties:
            type: string
          description: >-
            Headers the URL was signed with, sent exactly as given. Allowed:
            Content-Type, Content-MD5, Content-Disposition, Content-Encoding,
            Content-Language, Cache-Control, and x-amz-*, x-goog-* or x-ms-*
            headers.
          title: Headers
          type: object
      required:
        - url
      title: UploadTargetRequest
      type: object
    WatermarkPlacement:
      additionalProperties: false
      description: Watermark placement configuration.
      properties:
        position:
          $ref: '#/components/schemas/WatermarkPosition'
          default: bottom_right
          description: Anchor corner for the watermark.
        offset_x:
          anyOf:
            - maximum: 1
              minimum: -1
              type: number
            - type: 'null'
          default: null
          description: >-
            Fine-tune horizontal position. Fraction of frame width; 0.05 shifts
            5% rightward, -0.05 shifts 5% leftward.
          title: Offset X
        offset_y:
          anyOf:
            - maximum: 1
              minimum: -1
              type: number
            - type: 'null'
          default: null
          description: >-
            Fine-tune vertical position. Fraction of frame height; 0.05 shifts
            5% downward, -0.05 shifts 5% upward.
          title: Offset Y
      title: WatermarkPlacement
      type: object
    CaptionFileFormat:
      description: Supported caption file output formats.
      enum:
        - srt
      title: CaptionFileFormat
      type: string
    CaptionStyle:
      description: Visual style applied when burning captions into the rendered video.
      enum:
        - default
      title: CaptionStyle
      type: string
    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
    StudioAvatarInput:
      additionalProperties: false
      description: >-
        Avatar-driven source for an ``avatar_video`` studio scene.


        Mirrors the standalone ``avatar`` creation mode
        (``CreateVideoFromAvatar``)

        minus the output settings, which are global on the studio request.
        Provide

        exactly one audio source: `script`, `audio_url`, or `audio_asset_id`.

        `voice_settings` applies to a `script` spoken using `voice_id` or the
        avatar's default voice.
      properties:
        script:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          default: null
          description: >-
            Text script for the avatar to speak. Pair with voice_id, or omit
            voice_id when using avatar_id to use the avatar's default voice.
            Mutually exclusive with audio_url/audio_asset_id.
          title: Script
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Voice ID for text-to-speech. Required when script is provided,
            unless avatar_id is set (the avatar's default voice is used as
            fallback).
          title: Voice Id
        audio_url:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Public http(s) URL of an audio file to lip-sync. Mutually exclusive
            with script. Not a local or sandbox path (/mnt/data/..., file://);
            upload it and pass audio_asset_id.
          title: Audio Url
        audio_asset_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            HeyGen asset ID of an uploaded audio file. Mutually exclusive with
            script.
          title: Audio Asset Id
        voice_settings:
          anyOf:
            - $ref: '#/components/schemas/VoiceSettingsInput'
            - type: 'null'
          default: null
          description: >-
            Voice settings. Always include engine_settings: the engine from GET
            /v3/videos/voice-capabilities, and a model only when that row lists
            models. locale is optional and is the accent only.
        type:
          const: avatar
          description: Must be 'avatar' for an avatar-driven scene source.
          title: Type
          type: string
        avatar_id:
          description: HeyGen avatar ID (video avatar or photo avatar look ID).
          title: Avatar Id
          type: string
        motion_prompt:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Natural-language prompt controlling avatar body motion and hand
            gestures. Supported for photo avatars on either engine, and for
            video avatars when engine.type is 'avatar_v'. Rejected for video
            avatars on the default Avatar IV engine, and for photo avatars on
            'avatar_v' when the avatar's group has no animation reference (no
            digital twin or curated reference look).
          title: Motion Prompt
        expressiveness:
          anyOf:
            - $ref: '#/components/schemas/Expressiveness'
            - type: 'null'
          default: null
          description: >-
            Avatar expressiveness level. Photo avatars only. Defaults to 'low'
            when omitted. Avatar IV only; rejected when engine.type is
            'avatar_v'.
        engine:
          anyOf:
            - discriminator:
                mapping:
                  avatar_iii: '#/components/schemas/AvatarIIIEngineConfig'
                  avatar_iv: '#/components/schemas/AvatarIVEngineConfig'
                  avatar_v: '#/components/schemas/AvatarVEngineConfig'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/AvatarVEngineConfig'
                - $ref: '#/components/schemas/AvatarIVEngineConfig'
                - $ref: '#/components/schemas/AvatarIIIEngineConfig'
            - type: 'null'
          default: null
          description: >-
            Engine configuration for video generation. Pass {"type": "avatar_v"}
            to enable cross-reference-driven animation for higher quality. Check
            supported_api_engines on the avatar look to confirm eligibility.
            Defaults to Avatar IV when omitted.
          title: Engine
        background:
          anyOf:
            - discriminator:
                mapping:
                  color: '#/components/schemas/StudioColorBackgroundInput'
                  image: '#/components/schemas/StudioImageBackgroundInput'
                  video: '#/components/schemas/StudioVideoBackgroundInput'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/StudioColorBackgroundInput'
                - $ref: '#/components/schemas/StudioImageBackgroundInput'
                - $ref: '#/components/schemas/StudioVideoBackgroundInput'
            - type: 'null'
          default: null
          description: >-
            Optional scene background composited behind the avatar. Pass
            {"type": "color", "color": "#RRGGBB"} for a solid color, or {"type":
            "image", "source": {...}} or {"type": "video", "source": {...}} with
            the same asset input image and video scenes take. Image and video
            backgrounds cover the frame; a video background is muted and loops
            for the whole scene.
          title: Background
        remove_background:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: >-
            Remove the avatar background. Video avatars must be trained with
            matting enabled.
          title: Remove Background
      required:
        - type
        - avatar_id
      title: StudioAvatarInput
      type: object
    PlaybackInput:
      additionalProperties: false
      description: >-
        Playback and audio capability for a video-clip scene.


        ``mode`` controls how a narrated clip is reconciled to the
        voiceover-driven

        scene duration. ``volume`` must be between 0.0 and 1.0.
      properties:
        mode:
          anyOf:
            - enum:
                - freeze
                - loop
                - fit_to_scene
              type: string
            - type: 'null'
          default: null
          description: >-
            How a narrated clip aligns to the voiceover-driven scene duration.
            'freeze' plays once and holds the last frame; 'loop' repeats the
            clip; 'fit_to_scene' adjusts playback speed to exactly match the
            scene. Defaults to 'freeze' when omitted. Requires a video-scene
            voiceover.
          title: Mode
        volume:
          default: 1
          description: Clip audio volume. 1.0 = source level (default), 0.0 = silent.
          maximum: 1
          minimum: 0
          title: Volume
          type: number
        mute:
          default: false
          description: If True, force the clip silent regardless of 'volume'.
          title: Mute
          type: boolean
      title: PlaybackInput
      type: object
    WatermarkPosition:
      description: Anchor corner for a custom watermark overlay.
      enum:
        - top_left
        - top_right
        - bottom_left
        - bottom_right
      title: WatermarkPosition
      type: string
    StudioColorBackgroundInput:
      additionalProperties: false
      description: Solid-color background for an ``avatar_video`` studio scene.
      properties:
        type:
          const: color
          description: Background type discriminator. Must be 'color'.
          title: Type
          type: string
        color:
          description: Background color as a 6-digit hex string, e.g. '#1a2b3c'.
          pattern: ^#[0-9a-fA-F]{6}$
          title: Color
          type: string
      required:
        - type
        - color
      title: StudioColorBackgroundInput
      type: object
    StudioImageBackgroundInput:
      additionalProperties: false
      description: >-
        Image background for an ``avatar_video`` studio scene, scaled to cover
        the frame.


        ``source`` is the same asset input an ``image`` scene takes, resolved
        the same way.
      properties:
        type:
          const: image
          description: Background type discriminator. Must be 'image'.
          title: Type
          type: string
        source:
          description: >-
            Background image, scaled to cover the frame. Accepts a URL or an
            asset ID; inline base64 is not supported for studio scenes.
          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: Source
      required:
        - type
        - source
      title: StudioImageBackgroundInput
      type: object
    StudioVideoBackgroundInput:
      additionalProperties: false
      description: >-
        Video background for an ``avatar_video`` studio scene, scaled to cover
        the frame.


        ``source`` is the same asset input a ``video`` scene takes, resolved the
        same way. The clip

        is muted so it never competes with the avatar's voice, and loops for the
        whole scene.
      properties:
        type:
          const: video
          description: Background type discriminator. Must be 'video'.
          title: Type
          type: string
        source:
          description: >-
            Background video, scaled to cover the frame, muted, and looped for
            the length of the scene. Accepts a URL or an asset ID; inline base64
            is not supported for studio scenes.
          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: Source
      required:
        - type
        - source
      title: StudioVideoBackgroundInput
      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.