> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

> Browse example HeyGen CLI workflows from one-off video generation to multi-step automation. Each example shows the prompt, command, and resulting video.

## Create a Video with the Agent

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

```bash theme={null}
heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds"
```

```json Output theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": "vid_xyz789",
    "created_at": 1711288320
  }
}
```

Block until the video is ready:

```bash theme={null}
heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds" --wait
```

Browse available styles first, then apply one:

```bash theme={null}
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`:

```bash theme={null}
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
```

```json Output theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
heygen video create --request-schema
```

***

## Download a Video

Download the video file once it's complete:

```bash theme={null}
heygen video download vid_qr8821 --output-path ./my-video.mp4
```

```json Output theme={null}
{
  "asset": "video",
  "message": "Downloaded video to ./my-video.mp4",
  "path": "./my-video.mp4"
}
```

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

```bash theme={null}
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:

```bash theme={null}
heygen voice speech create \
  --text "Hello world, welcome to HeyGen." \
  --voice-id 1bd001e7e50f421d891986aad5e3e5d2
```

```json Output theme={null}
{
  "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:

```bash theme={null}
heygen voice create --prompt "warm, confident female narrator"
```

```json Output theme={null}
{
  "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:

```bash theme={null}
heygen voice create --prompt "warm, confident female narrator" --seed 1
```

***

## List and Filter Voices

Browse voices available for TTS:

```bash theme={null}
heygen voice list --language English --gender female --limit 5
```

```json Output theme={null}
{
  "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:

```bash theme={null}
heygen avatar looks list --group-id avt_angela_01 --limit 5
```

```json Output theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
heygen asset create --file ./my-photo.jpg
```

```json Output theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
heygen video-translate create \
  --output-languages es \
  --mode precision \
  --wait
```

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

```bash theme={null}
cat request.json | heygen video-translate create -d - --wait
```

Without `--wait`:

```json Output theme={null}
{
  "data": {
    "video_translation_ids": ["trl_55f"]
  }
}
```

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

Manage existing translations:

```bash theme={null}
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:

```bash theme={null}
heygen webhook endpoints create \
  --url "https://example.com/webhook" \
  --events "avatar_video.success,avatar_video.fail"
```

```json Output theme={null}
{
  "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"
  }
}
```

<Info>
  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.
</Info>

List all available event types:

```bash theme={null}
heygen webhook event-types list
```

Update or delete an endpoint:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
cat request.json | heygen video create -d - --wait
```

### Page through all your videos

```bash theme={null}
# 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)

```bash theme={null}
heygen avatar list --human
```

### Check your remaining credits

```bash theme={null}
heygen user me get | jq '.data.wallet'
```