Create a video

Create a video from a HeyGen avatar or an arbitrary image. Set type to ‘avatar’ to use a previously created avatar, or ‘image’ to animate a custom image. Both modes support text-to-speech scripts or pre-recorded audio for lip-sync. The video is generated asynchronously — poll status via GET /v3/videos/.

POST /v3/videos

Create a video

cURL

curl --request POST \
  --url https://api.heygen.com/v3/videos \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "<string>",
  "avatar_id": "<string>",
  "title": "<string>",
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "background": {
    "type": "color",
    "value": "<string>",
    "url": "<string>",
    "asset_id": "<string>"
  },
  "remove_background": true,
  "callback_url": "<string>",
  "callback_id": "<string>",
  "script": "<string>",
  "voice_id": "<string>",
  "audio_url": "<string>",
  "audio_asset_id": "<string>",
  "voice_settings": {
    "speed": 1,
    "pitch": 0,
    "locale": "<string>"
  },
  "motion_prompt": "<string>",
  "expressiveness": "high"
}
'

200

{}

Authorizations

ApiKeyAuthBearerAuth

x-api-key · string · header · required

HeyGen API key. Obtain from your HeyGen dashboard.

Body

application/json

CreateVideoFromAvatar

CreateVideoFromImage

Create a video from a HeyGen avatar (video or photo avatar).

Provide an avatar_id to use a previously created avatar. The server automatically selects the appropriate engine based on the avatar type (video avatar or photo avatar).

type · string · required

Must be 'avatar' for avatar-based video creation.

Allowed value: "avatar"

avatar_id · string · required

HeyGen avatar ID (video avatar or photo avatar look ID).

title · string | null

Display title for the video in the HeyGen dashboard.

resolution · enum<string> | null

Output video resolution.

Available options: 1080p, 720p

aspect_ratio · enum<string> | null

Output video aspect ratio.

Available options: 16:9, 9:16

background · BackgroundSetting · object

Background settings for the video.

Show child attributes

remove_background · boolean | null

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

callback_url · string | null

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

callback_id · string | null

Caller-defined identifier echoed back in the webhook payload.

script · string | null

Text script for the avatar to speak. Requires voice_id. Mutually exclusive with audio_url/audio_asset_id.

Minimum string length: 1

voice_id · string | null

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

audio_url · string | null

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

audio_asset_id · string | null

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

voice_settings · VoiceSettingsInput · object

Voice tuning parameters (speed, pitch, locale).

Show child attributes

motion_prompt · string | null

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

expressiveness · enum<string> | null

Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted.

Available options: high, medium, low

Response

200

application/json

Successful response

data · CreateAvatarVideoResponse · object

Show child attributes