Sign in
video

Heygen Create Avatar Video

Create an avatar video using HeyGen AV4 API (runs in background)

This endpoint:

  1. Downloads the provided image
  2. Uploads it to HeyGen as an asset
  3. Starts AV4 avatar video generation with the specified audio input
  4. Returns immediately with task_id and video_id (does not wait for completion)

Audio input options (exactly one required):

  • script + voice_id: Text-to-speech with specified voice
  • audio_url: External audio file URL
  • audio_asset_id: HeyGen audio asset ID

Returns: dict with: - task_id: Internal task ID for tracking - video_id: HeyGen video ID for status checking - status: Current task status ("In Progress")

Note: Use the check endpoint to poll for completion and get video URLs.

post/api/v1/video/heygen-create-avatar-video

Request body

image_urlstring required

URL of the image to use for avatar creation

video_titlestring

Title for the generated video

video_orientationstring

Video orientation: portrait or landscape

fitstring

Image fit: cover or contain

scriptstring nullable

Text script to be spoken (requires voice_id)

voice_idstring nullable

Voice ID for text-to-speech (required if script is provided)

audio_urlstring nullable

URL of audio file to use for lipsync

audio_asset_idstring nullable

HeyGen audio asset ID to use for lipsync

custom_motion_promptstring nullable

Custom motion prompt for avatar animation

enhance_custom_motion_promptboolean nullable

Whether to enhance the custom motion prompt

domain_idstring nullable

Optional domain ID for tracking

Response

Successful Response

{"stackTrail":"paths:/api/v1/video/heygen-create-avatar-video:post:responses:200:content:application/json:schema","oasType":"schema","type":"unknown"}

Changes

No recorded changes to this endpoint across all 3 revisions of this API.