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.

​
Steps

1

Browse available styles

List all visual styles to find one that fits:
heygen video-agent styles list

{
  "data": [
    {
      "style_id": "349d91e1ad2444eabab2672a9057f298",
      "name": "Thriller",
      "aspect_ratio": "16:9",
      "tags": ["cinematic"]
    },
    {
      "style_id": "be9f5b18fb294c99a0e34c15707145fc",
      "name": "Lego",
      "aspect_ratio": "16:9",
      "tags": ["handmade"]
    },
    {
      "style_id": "13898c3b01ec4dafae5fc17753c7dd7a",
      "name": "iOS",
      "aspect_ratio": "9:16",
      "tags": ["retro-tech"]
    }
  ]
}
Each style has an aspect_ratio — some are landscape (16:9), others portrait (9:16). Use --human for a readable table view.
Each style includes a preview_video_url and thumbnail_url — open them to preview the visual treatment before choosing.
2

Generate a styled video

Pass the style_id along with your prompt:
heygen video-agent create \
  --prompt "A 30-second explainer about how AI is transforming video production" \
  --style-id "349d91e1ad2444eabab2672a9057f298"

{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": "vid_xyz789",
    "created_at": 1711288320
  }
}
The agent picks the avatar, voice, and layout. The style controls the visual treatment.To override the agent’s choices, pass additional flags:
heygen video-agent create \
  --prompt "A product launch announcement" \
  --style-id "349d91e1ad2444eabab2672a9057f298" \
  --avatar-id "avt_angela_01" \
  --voice-id "1bd001e7e50f421d891986aad5e3e5d2" \
  --orientation landscape
3

Wait and download

# Block until ready
heygen video-agent create \
  --prompt "A quick intro to our company" \
  --style-id "be9f5b18fb294c99a0e34c15707145fc" \
  --wait

# Or poll manually
heygen video get vid_xyz789

# Download
heygen video download vid_xyz789 --output-path ./styled-video.mp4

​
Batch: same content, multiple styles

Generate the same prompt across different visual styles: 
#!/bin/bash
set -e

PROMPT="A 30-second pitch for an AI-powered design tool"

STYLES=(
  "349d91e1ad2444eabab2672a9057f298:Thriller"
  "be9f5b18fb294c99a0e34c15707145fc:Lego"
  "279082e3beda4ac5a4e9a4f2a36c7d74:Silent-Film"
)

for entry in "${STYLES[@]}"; do
  STYLE_ID="${entry%%:*}"
  STYLE_NAME="${entry##*:}"

  echo "Generating $STYLE_NAME..."
  VIDEO_ID=$(heygen video-agent create \
    --prompt "$PROMPT" \
    --style-id "$STYLE_ID" \
    | jq -r '.data.video_id')

  echo "  Video ID: $VIDEO_ID (generating...)"
done

echo "All videos submitted. Poll with: heygen video get <video-id>"

​
Interactive sessions for iteration

Review and refine before generating: 
# Start a session
SESSION=$(heygen video-agent sessions create \
  --prompt "A product demo video in Lego style" \
  --style-id "be9f5b18fb294c99a0e34c15707145fc" \
  | jq -r '.data.session_id')

# Check the storyboard
heygen video-agent sessions get "$SESSION"

# Send feedback
heygen video-agent sessions messages create "$SESSION" \
  -d '{"message": "Make the intro more energetic and add a CTA at the end"}'

# Stop if you want to start over
heygen video-agent sessions stop "$SESSION"

​
Available flags

FlagDescription
--promptText prompt describing the video (required)
--style-idVisual style from styles list
--avatar-idOverride the agent’s avatar choice
--voice-idOverride the agent’s voice choice
--orientationlandscape or portrait
--incognito-modeDisable memory for this session
--callback-urlWebhook URL for completion notifications
--waitBlock until ready (default timeout: 20 min)
--timeoutOverride wait timeout (e.g. --timeout 30m)