---
title: "Create an avatar video"
method: POST
path: "/v2/videos"
tags: ["Videos"]
---

# Create an avatar video

`POST /v2/videos`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v2/videos`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Creates a video from an avatar or image with an explicit avatar, voice and script. Runs asynchronously: poll GET /v2/videos/{video_id}. For a video planned from a prompt, use Video Agent.

## Request body

- CreateAvatarVideoRequest: Request body for POST /v2/videos — unified video creation.
  - `avatar_id` string, nullable: HeyGen avatar ID (photo avatar or video avatar). Mutually exclusive with image_url and image_asset_id.
  - `image_url` string, nullable: Public URL of an image to animate. Mutually exclusive with avatar_id and image_asset_id.
  - `image_asset_id` string, nullable: HeyGen asset ID of an uploaded image. Mutually exclusive with avatar_id and image_url.
  - `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.
  - `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.
  - `title` string, nullable: Display title for the video in the HeyGen dashboard.
  - `resolution` '4k' | '1080p' | '720p': Output video resolution. `4k` is available for Avatar III digital twins and studio avatars.
  - `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.
  - `motion_prompt` string, nullable: Natural-language prompt controlling avatar body motion. Photo avatars only.
  - `expressiveness` 'high' | 'medium' | 'low': Avatar expressiveness level for photo avatars.
  - `remove_background` boolean, nullable: Remove the avatar background. Video avatars must be trained with matting enabled.
  - `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.
  - `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. 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].
        - `model` 'eleven_multilingual_v2' | 'eleven_turbo_v2_5' | 'eleven_flash_v2_5' | 'eleven_v3' | 'eleven_v4': ElevenLabs model IDs exposed on the public API. Only current models are included — deprecated models (monolingual_v1, multilingual_v1, turbo_v2) are not accepted.
        - `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' | 's2.1-pro': Fish Audio model version.
        - `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.
  - `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.
  - `output_format` 'mp4' | 'webm': Output container for the generated video.

## 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`: Conflict
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v2/videos/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)