Examples - HeyGen Documentation

Create a Video with the Agent

Let the AI pick the avatar, voice, and layout from a text prompt:

heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds"

Output

{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": "vid_xyz789",
    "created_at": 1711288320
  }
}

Block until the video is ready:

heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds" --wait

Browse available styles first, then apply one:

heygen video-agent styles list
heygen video-agent create --prompt "Product launch" --style-id <style-id> --wait

Create a Video with Full Control

Skip the agent and specify every detail yourself using -d:

heygen video create -d '{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Welcome to our Q4 earnings call.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
  "aspect_ratio": "auto",
  "resolution": "1080p"
}' --wait

Output

{
  "data": {
    "id": "vid_qr8821",
    "status": "completed",
    "video_url": "https://files.heygen.com/video/vid_qr8821.mp4",
    "duration": 12.4,
    "created_at": 1711288320,
    "completed_at": 1711288422
  }
}

Animate a custom image instead of a preset avatar:

heygen video create -d '{
  "type": "image",
  "image": {"type": "url", "url": "https://example.com/photo.jpg"},
  "script": "Hello from HeyGen.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}' --wait

Discover all available request fields:

heygen video create --request-schema

Download a Video

Download the video file once it’s complete:

heygen video download vid_qr8821 --output-path ./my-video.mp4

Output

{
  "asset": "video",
  "message": "Downloaded video to ./my-video.mp4",
  "path": "./my-video.mp4"
}

Download the captioned version (requires enable_caption at creation time):

heygen video download vid_qr8821 --asset captioned --output-path ./my-video-captioned.mp4

Text to Speech

Generate standalone audio using the voice speech create command:

heygen voice speech create \
  --text "Hello world, welcome to HeyGen." \
  --voice-id 1bd001e7e50f421d891986aad5e3e5d2

Output

{
  "data": {
    "audio_url": "https://files.heygen.com/audio/req_abc123.mp3",
    "duration": 2.1,
    "request_id": "req_abc123"
  }
}

Design a Voice

Find a voice by describing what you want:

heygen voice create --prompt "warm, confident female narrator"

Output

{
  "data": {
    "voices": [
      {
        "voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
        "name": "Jenny",
        "language": "English",
        "gender": "female",
        "preview_audio_url": "https://files.heygen.com/voice/jenny_preview.mp3"
      }
    ],
    "seed": 0
  }
}

Increment --seed to get a different batch of results with the same prompt:

heygen voice create --prompt "warm, confident female narrator" --seed 1

List and Filter Voices

Browse voices available for TTS:

heygen voice list --language English --gender female --limit 5

Output

{
  "data": [
    {
      "voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
      "name": "Jenny",
      "language": "English",
      "gender": "female",
      "type": "public",
      "preview_audio_url": "https://files.heygen.com/voice/jenny_preview.mp3"
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiMWJkMDAxZTcifQ"
}

Browse Avatar Looks

List all looks available for an avatar group:

heygen avatar looks list --group-id avt_angela_01 --limit 5

Output

{
  "data": [
    {
      "id": "angela_business_01",
      "name": "Business Suit",
      "avatar_type": "studio_avatar",
      "group_id": "avt_angela_01",
      "gender": "female",
      "tags": ["formal", "business"],
      "default_voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
      "preview_image_url": "https://files.heygen.com/look/angela_business_01.jpg"
    }
  ],
  "has_more": false,
  "next_token": null
}

The id from a look is what you pass as avatar_id in video create. Get details for a specific look:

heygen avatar looks get angela_business_01

Upload an Asset

Upload a file to use as an avatar image, audio source, or attachment in video-agent:

heygen asset create --file ./my-photo.jpg

Output

{
  "data": {
    "asset_id": "ast_abc123",
    "url": "https://files.heygen.com/asset/ast_abc123.jpg",
    "mime_type": "image/jpeg",
    "size_bytes": 204800
  }
}

Use the returned asset_id anywhere the API accepts an asset input:

heygen video create -d '{
  "type": "image",
  "image": {"type": "asset_id", "asset_id": "ast_abc123"},
  "script": "Hello from my photo.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}' --wait

Translate a Video

Dub and lip-sync an existing video into Spanish:

heygen video-translate create \
  --output-languages es \
  --mode precision \
  --wait

For complex options (custom audio, SRT files), use -d:

cat request.json | heygen video-translate create -d - --wait

Without --wait:

Output

{
  "data": {
    "video_translation_ids": ["trl_55f"]
  }
}

--wait only supports single-language translations. For batch (multiple output_languages), poll each ID individually with heygen video-translate get.

Manage existing translations:

heygen video-translate list
heygen video-translate get trl_55f
heygen video-translate caption get trl_55f --format srt
heygen video-translate delete trl_55f --force

Webhooks

heygen webhook endpoints create \
  --url "https://example.com/webhook" \
  --events "avatar_video.success,avatar_video.fail"

Output

{
  "data": {
    "endpoint_id": "ep_abc123",
    "url": "https://example.com/webhook",
    "events": ["avatar_video.success", "avatar_video.fail"],
    "status": "enabled",
    "created_at": "2025-03-24T14:32:00Z",
    "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Store the secret securely — it’s used to verify webhook signatures and won’t be shown again. Use heygen webhook endpoints rotate-secret <endpoint-id> to generate a new one.

List all available event types:

heygen webhook event-types list

Update or delete an endpoint:

heygen webhook endpoints update ep_abc123 --events "avatar_video.success"
heygen webhook endpoints delete ep_abc123 --force

Scripting and Agent Integration

Since JSON is the default output and all non-data output goes to stderr, piping into other tools works without any extra flags.

Create a video and immediately open it in the browser

VIDEO_ID=$(heygen video-agent create --prompt "Demo video" | jq -r '.data.video_id')
heygen video get "$VIDEO_ID" --wait | jq -r '.data.video_url' | xargs open

Batch translate into multiple languages

for lang in es fr de ja ko; do
  heygen video-translate create \
    --output-languages "$lang" \
    --mode precision \
    --wait --quiet
  echo "✓ $lang done"
done

Create a video, wait, then download it

RESULT=$(heygen video create -d '{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Weekly update for the team.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}' --wait)

STATUS=$(echo "$RESULT" | jq -r '.data.status')
VIDEO_ID=$(echo "$RESULT" | jq -r '.data.id')

if [ "$STATUS" = "completed" ]; then
  heygen video download "$VIDEO_ID" --output-path weekly-update.mp4
fi

Pipe a JSON file into video create

cat request.json | heygen video create -d - --wait

Page through all your videos

# Fetch first page
heygen video list --limit 50

# Fetch next page using the token from the previous response
heygen video list --limit 50 --token "eyJsYXN0X2lkIjoiYXZ0X21hcmN1c18wMiJ9"

List all avatar names (human-readable)

heygen avatar list --human

Check your remaining credits

heygen user me get | jq '.data.wallet'

​Create a Video with the Agent

​Create a Video with Full Control

​Download a Video

​Text to Speech

​Design a Voice

​List and Filter Voices

​Browse Avatar Looks

​Upload an Asset

​Translate a Video

​Webhooks

​Scripting and Agent Integration

​Create a video and immediately open it in the browser

​Batch translate into multiple languages

​Create a video, wait, then download it

​Pipe a JSON file into video create

​Page through all your videos

​List all avatar names (human-readable)

​Check your remaining credits

Create a Video with the Agent

Create a Video with Full Control

Download a Video

Text to Speech

Design a Voice

List and Filter Voices

Browse Avatar Looks

Upload an Asset

Translate a Video

Webhooks

Scripting and Agent Integration

Create a video and immediately open it in the browser

Batch translate into multiple languages

Create a video, wait, then download it

Pipe a JSON file into video create

Page through all your videos

List all avatar names (human-readable)

Check your remaining credits