HEheygen
Videos

Create an avatar video

Changed on

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.

post/v2/videos

Request

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

Request body

avatar_idstring nullable

HeyGen avatar ID (photo avatar or video avatar). Mutually exclusive with image_url and image_asset_id.

image_urlstring nullable

Public URL of an image to animate. Mutually exclusive with avatar_id and image_asset_id.

image_asset_idstring nullable

HeyGen asset ID of an uploaded image. Mutually exclusive with avatar_id and image_url.

scriptstring 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_idstring 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_urlstring nullable

Public URL of an audio file to lip-sync. Mutually exclusive with script.

audio_asset_idstring nullable

HeyGen asset ID of an uploaded audio file. Mutually exclusive with script.

titlestring 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_promptstring nullable

Natural-language prompt controlling avatar body motion. Photo avatars only.

expressiveness'high' | 'medium' | 'low'

Avatar expressiveness level for photo avatars.

remove_backgroundboolean nullable

Remove the avatar background. Video avatars must be trained with matting enabled.

callback_urlstring nullable

Webhook URL to receive a POST notification when the video is ready.

callback_idstring nullable

Caller-defined identifier echoed back in the webhook payload.

output_format'mp4' | 'webm'

Output container for the generated video.

Response

Successful response

Example response

{
  "data": {
    "video_id": "v_abc123def456",
    "status": "waiting"
  }
}

Changes