Generate Video

post

https://api.heygen.com/v2/videos

Create a video from an avatar or image with Avatar IV. Supports photo avatars, digital twins, and direct image input. The video is generated asynchronously — poll status via GET /v2/videos/{video_id}.

Body Params

avatar_id

string

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

image_url

string

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

image_asset_id

string

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

script

string

Text script for the avatar to speak. Requires voice_id.

voice_id

string

Voice ID for text-to-speech or speech-to-speech. Required when script is provided.

audio_url

string

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

audio_asset_id

string

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

title

string

Display title for the video in the HeyGen dashboard.

resolution

string

enum

Defaults to 1080p

Output video resolution.

Allowed:

aspect_ratio

string

enum

Defaults to 16:9

Output video aspect ratio.

Allowed:

motion_prompt

string

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

expressiveness

string

enum

Avatar expressiveness level: 'high', 'medium', or 'low'. Photo avatars only. Defaults to 'low' when omitted.

Allowed:

remove_background

boolean

Defaults to false

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

background

object

Background settings for the video.

voice_settings

object

Voice tuning parameters (speed, pitch, locale).

Response

Language

Credentials

Header

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200