Skip to main content
POST
/
v3
/
videos
Create Video
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": "4k",
  "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"
}
'
{
  "data": {
    "video_id": "<string>",
    "status": "<string>"
  }
}

Authorizations

​
x-api-key
string
header
required

HeyGen API key. Obtain from your HeyGen dashboard.

Body

application/json

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:
4k,
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.

​
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. 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.

Minimum string length: 1
​
voice_id
string | null

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 | 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).

​
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

Successful response

​
data
CreateAvatarVideoResponse · object