---
title: "Create Video"
method: POST
path: "/v3/videos"
tags: ["Videos"]
---

# Create Video

`POST /v3/videos`

Creates a video from a HeyGen avatar or an arbitrary image. Supports scripts or pre-recorded audio for lip-sync. Supports the Avatar III, Avatar IV, and Avatar V engines; set the 'engine' field to select. Avatar IV is used by default when 'engine' is omitted.

## Headers

- `Idempotency-Key` string

## Request body

- union — Discriminated union for POST /v3/videos request body.
  - CreateVideoFromAvatar — 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.
    - `title` string, nullable — Display title for the video in the HeyGen dashboard.
    - `resolution` '4k' | '1080p' | '720p' — Output video resolution.
    - `aspect_ratio` '16:9' | '9:16' | '4:5' | '5:4' | '1:1' | 'auto', nullable — 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.
    - `fit` 'contain' | 'cover' — How the avatar is scaled to the output canvas.
    - `background` BackgroundSetting — Background configuration for the generated video.
      - `type` 'color' | 'image', required — Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.
      - `value` string, nullable — Hex color code (e.g. '#ff0000'). Required when type is 'color'.
      - `url` string, nullable — URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.
      - `asset_id` string, nullable — HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.
    - `remove_background` boolean, nullable — Remove the avatar background. Video avatars must be trained with matting enabled.
    - `callback_url` string, nullable — Webhook URL to receive a POST notification when the video is ready.
    - `callback_id` string, nullable — Caller-defined identifier echoed back in the webhook payload.
    - `watermark` object, nullable — Watermark configuration for video creation.
      - `image` union, required — Image asset to use as the watermark overlay (PNG or JPEG).
        - AssetUrl — Asset input via publicly accessible HTTPS URL.
          - `type` 'url', required — Input type discriminator
          - `url` string, required — Publicly accessible HTTPS URL for the asset
        - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
          - `type` 'asset_id', required — Input type discriminator
          - `asset_id` string, required — HeyGen asset ID from the asset upload endpoint
        - AssetBase64 — Asset input via base64-encoded content.
          - `type` 'base64', required — Input type discriminator
          - `media_type` string, required — MIME type of the encoded content (e.g. "image/png")
          - `data` string, required — Base64-encoded file content
      - `scale` number — Scale multiplier for the watermark image. 1.0 renders at native size.
      - `opacity` number — Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.
      - `placement` WatermarkPlacement — Watermark placement configuration.
        - `position` 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right' — Anchor corner for a custom watermark overlay.
        - `offset_x` number, nullable — Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.
        - `offset_y` number, nullable — Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.
    - `caption` CaptionSetting — 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.
      - `file_format` 'srt' — Supported caption file output formats.
      - `style` 'default' — Visual style applied when burning captions into the rendered video.
    - `output_format` 'mp4' | 'webm' — Output container for the generated video.
    - `script` string, nullable — 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.
    - `voice_id` string, nullable — 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).
    - `audio_url` string, nullable — Public URL of an audio file to lip-sync. Mutually exclusive with script.
    - `audio_asset_id` string, nullable — HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.
    - `voice_settings` VoiceSettingsInput — Voice tuning parameters for text-to-speech. Applies only when 'script' + 'voice_id' are provided — not when audio_url/audio_asset_id is used (uploaded audio bypasses TTS).
      - `speed` number — Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).
      - `pitch` number — Pitch adjustment in semitones. -50 to +50.
      - `volume` number — Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.
      - `locale` string, nullable — Locale/accent hint for multi-lingual voices (e.g. 'en-US').
      - `engine_settings` union — Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.
        - ElevenLabsEngineSettings — Engine-specific voice settings for ElevenLabs-backed voices. Inherits the ElevenLabs tuning fields (model, stability, similarity_boost, style, use_speaker_boost) along with the eleven_v3 stability validator from :class:`movio.api_service.app.api_types.video.ElevenLabsSettings`.
          - `model` 'eleven_multilingual_v2' | 'eleven_turbo_v2_5' | 'eleven_flash_v2_5' | 'eleven_v3' — ElevenLabs model IDs exposed on the public API. Only current models are included — deprecated models (monolingual_v1, multilingual_v1, turbo_v2) are not accepted. The web auto-remaps them to newer equivalents; the API should not offer models we wouldn't recommend using.
          - `similarity_boost` number, nullable — The similarity boost parameter for ElevenLabs.
          - `stability` number, nullable — The stability parameter for ElevenLabs.
          - `style` number, nullable — The style parameter for ElevenLabs.
          - `use_speaker_boost` boolean, nullable — Whether to use speaker boost for ElevenLabs.
          - `engine_type` 'elevenlabs', required — Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.
        - FishEngineSettings — Engine-specific voice settings for Fish Audio-backed voices. Inherits Fish's tuning fields (model, stability, similarity).
          - `model` 's1' | 's2-pro' — Fish Audio model version. Mirrors the choices exposed on the web (FISH_MODELS).
          - `stability` number, nullable — Stability parameter; higher is more consistent.
          - `similarity` number, nullable — Similarity parameter; how closely to match the source voice.
          - `engine_type` 'fish', required — Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.
        - StarfishEngineSettings — Engine-selection for Starfish-backed voices. Starfish has no user-tunable settings today; set ``engine_type='starfish'`` to force Starfish routing on voices that support multiple engines.
          - `engine_type` 'starfish', required — Engine type discriminator. Must be 'starfish' for Starfish-backed voices.
    - `type` 'avatar', required — Must be 'avatar' for avatar-based video creation.
    - `avatar_id` string, required — HeyGen avatar ID (video avatar or photo avatar look ID).
    - `motion_prompt` string, nullable — 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.
    - `expressiveness` 'high' | 'medium' | 'low' — Avatar expressiveness level for photo avatars.
    - `engine` union — 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.
      - AvatarVEngineConfig — Avatar V engine configuration with cross-reference-driven animation.
        - `type` 'avatar_v', required — Engine type discriminator. Must be 'avatar_v'. Check supported_api_engines on the avatar look to confirm eligibility.
        - `reference_look_id` string, nullable — Optional instant_avatar look to use as the animation reference. Must be an `instant_avatar` look (studio / photo / other look types are rejected) belonging to the same avatar group as `avatar_id`. When omitted, video avatars self-reference and photo avatars auto-select the best instant_avatar sibling in their group.
      - AvatarIVEngineConfig — Avatar IV engine configuration (default behavior).
        - `type` 'avatar_iv', required — Engine type discriminator. Must be 'avatar_iv'.
      - AvatarIIIEngineConfig — 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.
        - `type` 'avatar_iii', required — 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.
  - CreateVideoFromImage — Create a video by animating an arbitrary image. 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.
    - `title` string, nullable — Display title for the video in the HeyGen dashboard.
    - `resolution` '4k' | '1080p' | '720p' — Output video resolution.
    - `aspect_ratio` '16:9' | '9:16' | '4:5' | '5:4' | '1:1' | 'auto', nullable — 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.
    - `fit` 'contain' | 'cover' — How the avatar is scaled to the output canvas.
    - `background` BackgroundSetting — Background configuration for the generated video.
      - `type` 'color' | 'image', required — Background type. 'color' uses a solid hex color; 'image' uses an image from url or asset_id.
      - `value` string, nullable — Hex color code (e.g. '#ff0000'). Required when type is 'color'.
      - `url` string, nullable — URL of the background image. Used when type is 'image'. Mutually exclusive with asset_id.
      - `asset_id` string, nullable — HeyGen asset ID of the background image. Used when type is 'image'. Mutually exclusive with url.
    - `remove_background` boolean, nullable — Remove the avatar background. Video avatars must be trained with matting enabled.
    - `callback_url` string, nullable — Webhook URL to receive a POST notification when the video is ready.
    - `callback_id` string, nullable — Caller-defined identifier echoed back in the webhook payload.
    - `watermark` object, nullable — Watermark configuration for video creation.
      - `image` union, required — Image asset to use as the watermark overlay (PNG or JPEG).
        - AssetUrl — Asset input via publicly accessible HTTPS URL.
          - `type` 'url', required — Input type discriminator
          - `url` string, required — Publicly accessible HTTPS URL for the asset
        - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
          - `type` 'asset_id', required — Input type discriminator
          - `asset_id` string, required — HeyGen asset ID from the asset upload endpoint
        - AssetBase64 — Asset input via base64-encoded content.
          - `type` 'base64', required — Input type discriminator
          - `media_type` string, required — MIME type of the encoded content (e.g. "image/png")
          - `data` string, required — Base64-encoded file content
      - `scale` number — Scale multiplier for the watermark image. 1.0 renders at native size.
      - `opacity` number — Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.
      - `placement` WatermarkPlacement — Watermark placement configuration.
        - `position` 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right' — Anchor corner for a custom watermark overlay.
        - `offset_x` number, nullable — Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.
        - `offset_y` number, nullable — Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.
    - `caption` CaptionSetting — 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.
      - `file_format` 'srt' — Supported caption file output formats.
      - `style` 'default' — Visual style applied when burning captions into the rendered video.
    - `output_format` 'mp4' | 'webm' — Output container for the generated video.
    - `script` string, nullable — 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.
    - `voice_id` string, nullable — 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).
    - `audio_url` string, nullable — Public URL of an audio file to lip-sync. Mutually exclusive with script.
    - `audio_asset_id` string, nullable — HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.
    - `voice_settings` VoiceSettingsInput — Voice tuning parameters for text-to-speech. Applies only when 'script' + 'voice_id' are provided — not when audio_url/audio_asset_id is used (uploaded audio bypasses TTS).
      - `speed` number — Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).
      - `pitch` number — Pitch adjustment in semitones. -50 to +50.
      - `volume` number — Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.
      - `locale` string, nullable — Locale/accent hint for multi-lingual voices (e.g. 'en-US').
      - `engine_settings` union — Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.
        - ElevenLabsEngineSettings — Engine-specific voice settings for ElevenLabs-backed voices. Inherits the ElevenLabs tuning fields (model, stability, similarity_boost, style, use_speaker_boost) along with the eleven_v3 stability validator from :class:`movio.api_service.app.api_types.video.ElevenLabsSettings`.
          - `model` 'eleven_multilingual_v2' | 'eleven_turbo_v2_5' | 'eleven_flash_v2_5' | 'eleven_v3' — ElevenLabs model IDs exposed on the public API. Only current models are included — deprecated models (monolingual_v1, multilingual_v1, turbo_v2) are not accepted. The web auto-remaps them to newer equivalents; the API should not offer models we wouldn't recommend using.
          - `similarity_boost` number, nullable — The similarity boost parameter for ElevenLabs.
          - `stability` number, nullable — The stability parameter for ElevenLabs.
          - `style` number, nullable — The style parameter for ElevenLabs.
          - `use_speaker_boost` boolean, nullable — Whether to use speaker boost for ElevenLabs.
          - `engine_type` 'elevenlabs', required — Engine type discriminator. Must be 'elevenlabs' for ElevenLabs-backed voices.
        - FishEngineSettings — Engine-specific voice settings for Fish Audio-backed voices. Inherits Fish's tuning fields (model, stability, similarity).
          - `model` 's1' | 's2-pro' — Fish Audio model version. Mirrors the choices exposed on the web (FISH_MODELS).
          - `stability` number, nullable — Stability parameter; higher is more consistent.
          - `similarity` number, nullable — Similarity parameter; how closely to match the source voice.
          - `engine_type` 'fish', required — Engine type discriminator. Must be 'fish' for Fish Audio-backed voices.
        - StarfishEngineSettings — Engine-selection for Starfish-backed voices. Starfish has no user-tunable settings today; set ``engine_type='starfish'`` to force Starfish routing on voices that support multiple engines.
          - `engine_type` 'starfish', required — Engine type discriminator. Must be 'starfish' for Starfish-backed voices.
    - `type` 'image', required — Must be 'image' for image-based video creation.
    - `image` union, required — Image to animate. Accepts URL, asset ID, or base64-encoded data.
      - AssetUrl — Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required — Input type discriminator
        - `url` string, required — Publicly accessible HTTPS URL for the asset
      - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required — Input type discriminator
        - `asset_id` string, required — HeyGen asset ID from the asset upload endpoint
      - AssetBase64 — Asset input via base64-encoded content.
        - `type` 'base64', required — Input type discriminator
        - `media_type` string, required — MIME type of the encoded content (e.g. "image/png")
        - `data` string, required — Base64-encoded file content
    - `motion_prompt` string, nullable — Natural-language prompt controlling avatar body motion. Photo avatars only.
    - `expressiveness` 'high' | 'medium' | 'low' — Avatar expressiveness level for photo avatars.
  - CreateVideoFromCinematicAvatar — 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. Backed by the Seedance generation pipeline.
    - `type` 'cinematic_avatar', required — Must be 'cinematic_avatar' for prompt-and-reference video creation.
    - `prompt` string, required — Natural-language prompt describing the video to generate.
    - `avatar_id` string[], required — Avatar look ID(s) used as visual references. Provide 1 to 3 look IDs.
    - `references` union[], nullable — 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.
      - union
        - AssetUrl — Asset input via publicly accessible HTTPS URL.
          - `type` 'url', required — Input type discriminator
          - `url` string, required — Publicly accessible HTTPS URL for the asset
        - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
          - `type` 'asset_id', required — Input type discriminator
          - `asset_id` string, required — HeyGen asset ID from the asset upload endpoint
        - AssetBase64 — Asset input via base64-encoded content.
          - `type` 'base64', required — Input type discriminator
          - `media_type` string, required — MIME type of the encoded content (e.g. "image/png")
          - `data` string, required — Base64-encoded file content
    - `aspect_ratio` '16:9' | '9:16' | '4:5' | '5:4' | '1:1' | 'auto' — 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.
    - `resolution` '720p' | '1080p' — Output resolution. Supported for cinematic_avatar: '720p', '1080p'. Defaults to '720p'.
    - `auto_duration` boolean — Let the model choose the video length. When true, omit duration.
    - `duration` integer, nullable — Video length in seconds (4–15). Defaults to 10. Omit when auto_duration is true.
    - `enhance_prompt` boolean — Enable server-side prompt enhancement.
    - `title` string, nullable — Display title for the video in the HeyGen dashboard.
  - CreateVideoFromStudio — 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.
    - `type` 'studio', required — Must be 'studio' for scene-composition video creation.
    - `title` string, nullable — Display title for the video in the HeyGen dashboard.
    - `aspect_ratio` '16:9' | '9:16' | '4:5' | '5:4' | '1:1' | 'auto', nullable — 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.
    - `resolution` '4k' | '1080p' | '720p' — Output video resolution.
    - `callback_url` string, nullable — Webhook URL to receive a POST notification when the video is ready.
    - `callback_id` string, nullable — Caller-defined identifier echoed back in the webhook payload.
    - `caption` CaptionSetting — 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.
      - `file_format` 'srt' — Supported caption file output formats.
      - `style` 'default' — Visual style applied when burning captions into the rendered video.
    - `watermark` object, nullable — Watermark configuration for video creation.
      - `image` union, required — Image asset to use as the watermark overlay (PNG or JPEG).
        - AssetUrl — Asset input via publicly accessible HTTPS URL.
          - `type` 'url', required — Input type discriminator
          - `url` string, required — Publicly accessible HTTPS URL for the asset
        - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
          - `type` 'asset_id', required — Input type discriminator
          - `asset_id` string, required — HeyGen asset ID from the asset upload endpoint
        - AssetBase64 — Asset input via base64-encoded content.
          - `type` 'base64', required — Input type discriminator
          - `media_type` string, required — MIME type of the encoded content (e.g. "image/png")
          - `data` string, required — Base64-encoded file content
      - `scale` number — Scale multiplier for the watermark image. 1.0 renders at native size.
      - `opacity` number — Watermark opacity. 0.0 is fully transparent, 1.0 is fully opaque.
      - `placement` WatermarkPlacement — Watermark placement configuration.
        - `position` 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right' — Anchor corner for a custom watermark overlay.
        - `offset_x` number, nullable — Fine-tune horizontal position. Fraction of frame width; 0.05 shifts 5% rightward, -0.05 shifts 5% leftward.
        - `offset_y` number, nullable — Fine-tune vertical position. Fraction of frame height; 0.05 shifts 5% downward, -0.05 shifts 5% upward.
    - `scenes` union[], required — Ordered list of whole-frame scenes to concatenate. Each scene is one of 'avatar_video', 'image', or 'video'. Must contain 1 to 50 scenes.
      - union
        - AvatarVideoScene — A whole-frame speaking scene backed by an avatar.
          - `type` 'avatar_video', required — Must be 'avatar_video' for an avatar speaking scene.
          - `input` StudioAvatarInput, required — 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. An audio source is required: exactly one of (script + voice_id), audio_url, or audio_asset_id.
            - `script` string, nullable — 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.
            - `voice_id` string, nullable — 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).
            - `audio_url` string, nullable — Public URL of an audio file to lip-sync. Mutually exclusive with script.
            - `audio_asset_id` string, nullable — HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.
            - `voice_settings` VoiceSettingsInput — Voice tuning parameters for text-to-speech. Applies only when 'script' + 'voice_id' are provided — not when audio_url/audio_asset_id is used (uploaded audio bypasses TTS).
              - …
            - `type` 'avatar', required — Must be 'avatar' for an avatar-driven scene source.
            - `avatar_id` string, required — HeyGen avatar ID (video avatar or photo avatar look ID).
            - `motion_prompt` string, nullable — 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.
            - `expressiveness` 'high' | 'medium' | 'low' — Avatar expressiveness level for photo avatars.
            - `engine` union — 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.
              - …
            - `background` StudioColorBackgroundInput — Solid-color background for an ``avatar_video`` studio scene. v1 is COLOR-ONLY. Kept as a type-discriminated model so future ``image`` / ``video`` / ``blur`` background variants slot into ``StudioBackgroundInput`` without changing the color wire shape.
              - …
        - ImageScene — 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.
          - `type` 'image', required — Must be 'image' for a still-image scene.
          - `source` union, required — Still image to display. Accepts URL, asset ID, or base64-encoded data.
            - AssetUrl — Asset input via publicly accessible HTTPS URL.
              - …
            - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
              - …
            - AssetBase64 — Asset input via base64-encoded content.
              - …
          - `duration` number, nullable — Silent mode: hold the still image for this many seconds. Mutually exclusive with any audio source. Must be > 0 and <= 300.
          - `script` string, nullable — Narrated mode: text to speak over the image. Pair with voice_id. Mutually exclusive with duration/audio_url/audio_asset_id.
          - `voice_id` string, nullable — Voice ID for text-to-speech. Required when script is provided.
          - `audio_url` string, nullable — Narrated mode: public URL of an audio file to play over the image. Mutually exclusive with duration/script.
          - `audio_asset_id` string, nullable — Narrated mode: HeyGen asset ID of an uploaded audio file. Mutually exclusive with duration/script.
          - `voice_settings` VoiceSettingsInput — Voice tuning parameters for text-to-speech. Applies only when 'script' + 'voice_id' are provided — not when audio_url/audio_asset_id is used (uploaded audio bypasses TTS).
            - `speed` number — Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).
            - `pitch` number — Pitch adjustment in semitones. -50 to +50.
            - `volume` number — Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.
            - `locale` string, nullable — Locale/accent hint for multi-lingual voices (e.g. 'en-US').
            - `engine_settings` union — Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.
              - …
        - VideoScene — A whole-frame scene backed by an existing video clip. Optional ``playback`` exposes the audio volume / mute capability (PRINFRA-271); when omitted the clip plays at its source volume. Optional voiceover / narration (PRINFRA-303 / 304): 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 the clip is held/frozen behind it (mirroring the narrated-image timing path); when omitted the clip plays full-length as before. The clip's own audio level is still governed by ``playback`` (the two compose).
          - `type` 'video', required — Must be 'video' for a video-clip scene.
          - `source` union, required — Video clip to include. Accepts URL, asset ID, or base64-encoded data.
            - AssetUrl — Asset input via publicly accessible HTTPS URL.
              - …
            - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
              - …
            - AssetBase64 — Asset input via base64-encoded content.
              - …
          - `playback` PlaybackInput — Playback / audio capability for a video-clip scene (PRINFRA-271). The documented home for future trim / loop / speed controls (not exposed yet). Today it carries only the clip's audio level. Unknown fields are rejected (``extra="forbid"``) and out-of-range ``volume`` is rejected up front at the facade.
            - `volume` number — Clip audio volume. 1.0 = source level (default), 0.0 = silent.
            - `mute` boolean — If True, force the clip silent regardless of 'volume'.
          - `script` string, nullable — Optional voiceover: text to speak over the clip. Pair with voice_id. Mutually exclusive with audio_url/audio_asset_id.
          - `voice_id` string, nullable — Voice ID for text-to-speech. Required when script is provided.
          - `audio_url` string, nullable — Optional voiceover: public URL of an audio file to play over the clip. Mutually exclusive with script/audio_asset_id.
          - `audio_asset_id` string, nullable — Optional voiceover: HeyGen asset ID of an uploaded audio file. Mutually exclusive with script/audio_url.
          - `voice_settings` VoiceSettingsInput — Voice tuning parameters for text-to-speech. Applies only when 'script' + 'voice_id' are provided — not when audio_url/audio_asset_id is used (uploaded audio bypasses TTS).
            - `speed` number — Playback speed multiplier. 0.5 (half speed) to 1.5 (1.5x speed).
            - `pitch` number — Pitch adjustment in semitones. -50 to +50.
            - `volume` number — Voice audio volume. 1.0 = full, 0.0 = silent. Useful when mixing spoken voice with background audio.
            - `locale` string, nullable — Locale/accent hint for multi-lingual voices (e.g. 'en-US').
            - `engine_settings` union — Engine-specific voice tuning, discriminated by 'engine_type'. Use the variant matching the engine backing the chosen voice (e.g. engine_type='elevenlabs' for ElevenLabs-backed voices). The request is rejected if the voice_id is not compatible with the selected engine.
              - …

## Response `200`

Successful response

- object
  - `data` CreateAvatarVideoResponse
    - `video_id` string, required — Unique identifier for the created video.
    - `status` string, required — Initial video status (e.g. 'waiting').
    - `output_format` 'mp4' | 'webm' — Output container for the generated video.

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication failed
- `409` — A prior request with this Idempotency-Key is still in progress. Wait for the original request to complete, then retry.
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/heygen/apis/heygen-external-api.md) · [All operations](https://skmtc.net/heygen/apis/heygen-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heygen/heygen-external-api/revisions/e2e54726e210/schema)