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",
  "fit": "contain",
  "background": {
    "type": "color",
    "value": "<string>",
    "url": "<string>",
    "asset_id": "<string>"
  },
  "remove_background": true,
  "callback_url": "<string>",
  "callback_id": "<string>",
  "watermark": {
    "image": {
      "type": "<string>",
      "url": "<string>"
    },
    "scale": 1,
    "opacity": 1,
    "placement": {
      "position": "bottom_right",
      "offset_x": 0,
      "offset_y": 0
    }
  },
  "caption": {
    "file_format": "srt",
    "style": "default"
  },
  "output_format": "mp4",
  "script": "<string>",
  "voice_id": "<string>",
  "audio_url": "<string>",
  "audio_asset_id": "<string>",
  "voice_settings": {
    "speed": 1,
    "pitch": 0,
    "volume": 1,
    "locale": "<string>",
    "engine_settings": {
      "engine_type": "<string>",
      "model": "eleven_multilingual_v2",
      "similarity_boost": 0.5,
      "stability": 0.5,
      "style": 0.5,
      "use_speaker_boost": true
    }
  },
  "motion_prompt": "<string>",
  "expressiveness": "high",
  "engine": {
    "type": "<string>"
  }
}
'
{
  "data": {
    "video_id": "<string>",
    "status": "<string>",
    "output_format": "mp4"
  }
}

Documentation Index

Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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. Supports all avatar types: studio_avatar, digital_twin, and photo_avatar. Optionally set engine to select Avatar V for eligible avatars; when omitted, the server defaults to Avatar IV.

​
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
​
fit
enum<string> | null

How the subject is fitted to the output canvas. 'cover' scales to fill the frame (may crop edges). 'contain' scales to fit entirely within the frame (may show background). When omitted, the server picks the best option based on the source and canvas orientations.

Available options:
contain,
cover
​
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.

​
watermark
WatermarkInput · object

Custom watermark image to overlay on the video (PNG or JPEG). Available as a premium option for select Enterprise customers. To request access, please contact our support team.

​
caption
CaptionSetting · object

Caption generation settings. A sidecar subtitle file is always returned via subtitle_url; set 'style' to additionally burn captions into the rendered video.

​
output_format
enum<string>
default:mp4

Output container. 'webm' returns a video with a transparent background (alpha channel); 'mp4' (default) returns a standard video. 'webm' requires an avatar that supports matting. When 'webm' is selected, any 'background' value is rejected and background removal is applied automatically — the caller does not need to set 'remove_background'.

Available options:
mp4,
webm
​
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. Avatar IV only; not supported when engine.type is 'avatar_v'.

​
expressiveness
enum<string> | null

Avatar expressiveness level. Photo avatars only. Defaults to 'low' when omitted. Avatar IV only; not supported when engine.type is 'avatar_v'.

Available options:
high,
medium,
low
​
engine
AvatarVEngineConfig · object

Avatar V engine configuration with cross-reference-driven animation.

Response

Successful response

​
data
CreateAvatarVideoResponse · object