Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.heygen.com/llms.txt

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

​
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": "16:9",
  "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

Register an endpoint to receive event notifications: 
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'