---
title: "Heygen Create Avatar Video"
method: POST
path: "/api/v1/video/heygen-create-avatar-video"
tags: ["video"]
---

# Heygen Create Avatar Video

`POST /api/v1/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.

## Request body

- HeygenAvatarVideoDTO — DTO for HeyGen AV4 Avatar Video Generation
  - `image_url` string, required — URL of the image to use for avatar creation
  - `video_title` string — Title for the generated video
  - `video_orientation` string — Video orientation: portrait or landscape
  - `fit` string — Image fit: cover or contain
  - `script` string, nullable — Text script to be spoken (requires voice_id)
  - `voice_id` string, nullable — Voice ID for text-to-speech (required if script is provided)
  - `audio_url` string, nullable — URL of audio file to use for lipsync
  - `audio_asset_id` string, nullable — HeyGen audio asset ID to use for lipsync
  - `custom_motion_prompt` string, nullable — Custom motion prompt for avatar animation
  - `enhance_custom_motion_prompt` boolean, nullable — Whether to enhance the custom motion prompt
  - `domain_id` string, nullable — Optional domain ID for tracking

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/brandbooster/apis/fastapi.md) · [All operations](https://skmtc.dev/brandbooster/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/brandbooster/fastapi/revisions/a9374f6fe96c/schema)