> ## 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.

# Commands

> Reference every HeyGen CLI command with flags, examples, and expected output. Covers video, avatar, voice, translate, lipsync, and config commands in one place.

All commands follow the pattern `heygen <noun> <verb>`. The command surface is auto-generated from HeyGen's OpenAPI specification — when new v3 endpoints ship, the CLI picks them up automatically.

Run `heygen <command> --help` for detailed usage and examples on any command. Use `--request-schema` or `--response-schema` on any command to see the full JSON schema for its request or response — no auth required.

## Video Agent

Create videos from text prompts using AI. The agent picks avatar, voice, and layout automatically.

| Command                                                       | API Endpoint                                                | Description                                  |
| ------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------- |
| `heygen video-agent create`                                   | `POST /v3/video-agents`                                     | Create a video from a prompt                 |
| `heygen video-agent get <session-id>`                         | `GET /v3/video-agents/{session_id}`                         | Get session status and messages              |
| `heygen video-agent send <session-id>`                        | `POST /v3/video-agents/{session_id}`                        | Send a follow-up message or request revision |
| `heygen video-agent stop <session-id>`                        | `POST /v3/video-agents/{session_id}/stop`                   | Stop an in-progress session                  |
| `heygen video-agent resources get <session-id> <resource-id>` | `GET /v3/video-agents/{session_id}/resources/{resource_id}` | Get a session resource                       |
| `heygen video-agent styles list`                              | `GET /v3/video-agents/styles`                               | List available video styles                  |
| `heygen video-agent videos list <session-id>`                 | `GET /v3/video-agents/{session_id}/videos`                  | List videos produced by a session            |

### Flags for `video-agent create`

| Flag                    | Description                                                          |
| ----------------------- | -------------------------------------------------------------------- |
| `--prompt <text>`       | The message/prompt for video generation (required)                   |
| `--mode <value>`        | `generate` (default, one-shot) or `chat` (multi-turn with revisions) |
| `--avatar-id <id>`      | Specific avatar ID to use                                            |
| `--voice-id <id>`       | Specific voice ID to use for narration                               |
| `--style-id <id>`       | Style ID from `video-agent styles list`                              |
| `--orientation <value>` | `landscape` or `portrait` (auto-detected if omitted)                 |
| `--incognito-mode`      | Disable memory injection and extraction for this session             |
| `--callback-url <url>`  | Webhook URL for completion/failure notifications                     |
| `--callback-id <id>`    | ID echoed back in the webhook payload                                |

## Videos

Create, list, retrieve, and delete avatar videos with full parameter control.

| Command                            | API Endpoint                   | Description                             |
| ---------------------------------- | ------------------------------ | --------------------------------------- |
| `heygen video create`              | `POST /v3/videos`              | Create a video with explicit parameters |
| `heygen video list`                | `GET /v3/videos`               | List your videos                        |
| `heygen video get <video-id>`      | `GET /v3/videos/{video_id}`    | Get video details and status            |
| `heygen video delete <video-id>`   | `DELETE /v3/videos/{video_id}` | Delete a video                          |
| `heygen video download <video-id>` | Client-side                    | Download a video file to disk           |

### Flags for `video create`

`video create` uses a discriminated union request body — the `type` field determines which fields are valid. Pass the full body with `-d`:

```bash theme={null}
# Avatar-based video
heygen video create -d '{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Hello world",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}'

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

# Cinematic Avatar — prompt-driven, no script or voice (1–3 looks)
heygen video create -d '{
  "type": "cinematic_avatar",
  "prompt": "A founder walks through a sunlit startup office, shot handheld in a documentary style.",
  "avatar_id": ["your_look_id"],
  "resolution": "1080p",
  "duration": 10
}'
```

<Note>
  Cinematic Avatar supports `720p` and `1080p` only — 4K is not available for this type. See the [Cinematic Avatar guide](/cinematic-avatar) for the full parameter list.
</Note>

Run `heygen video create --request-schema` to see all available fields.

### Flags for `video list`

| Flag               | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `--limit <n>`      | Maximum items per page (1–100, default 10)                |
| `--token <cursor>` | Pagination cursor from a previous response's `next_token` |
| `--folder-id <id>` | Filter videos by folder ID                                |
| `--title <text>`   | Filter videos by title substring                          |

### Flags for `video download`

| Flag                   | Description                                  |
| ---------------------- | -------------------------------------------- |
| `--output-path <path>` | Output file path (default: `{video-id}.mp4`) |
| `--asset <type>`       | `video` (default) or `captioned`             |

## Avatars

Browse and manage avatars and their looks (outfits/styles).

| Command                                   | API Endpoint                          | Description              |
| ----------------------------------------- | ------------------------------------- | ------------------------ |
| `heygen avatar create`                    | `POST /v3/avatars`                    | Create an avatar         |
| `heygen avatar list`                      | `GET /v3/avatars`                     | List avatar groups       |
| `heygen avatar get <group-id>`            | `GET /v3/avatars/{group_id}`          | Get avatar group details |
| `heygen avatar looks list`                | `GET /v3/avatars/looks`               | List avatar looks        |
| `heygen avatar looks get <look-id>`       | `GET /v3/avatars/looks/{look_id}`     | Get avatar look details  |
| `heygen avatar looks update <look-id>`    | `PATCH /v3/avatars/looks/{look_id}`   | Rename an avatar look    |
| `heygen avatar consent create <group-id>` | `POST /v3/avatars/{group_id}/consent` | Initiate a consent flow  |

### Filter flags for `avatar list`

| Flag                  | Description                               |
| --------------------- | ----------------------------------------- |
| `--ownership <scope>` | `public` or `private`                     |
| `--limit <n>`         | Maximum items per page (1–50, default 20) |
| `--token <cursor>`    | Pagination cursor                         |

### Filter flags for `avatar looks list`

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--group-id <id>`      | Filter by avatar group                             |
| `--avatar-type <type>` | `studio_avatar`, `digital_twin`, or `photo_avatar` |
| `--ownership <scope>`  | `public` or `private`                              |
| `--limit <n>`          | Maximum items per page (1–50, default 20)          |
| `--token <cursor>`     | Pagination cursor                                  |

<Info>
  The `id` field on a look is what you pass as `avatar_id` to `video create`. The look's `avatar_type` field determines which engines and request parameters are compatible.
</Info>

## Voices

Browse voices and generate speech audio.

| Command                      | API Endpoint             | Description                                        |
| ---------------------------- | ------------------------ | -------------------------------------------------- |
| `heygen voice list`          | `GET /v3/voices`         | List voices                                        |
| `heygen voice create`        | `POST /v3/voices`        | Design a voice from a natural language description |
| `heygen voice speech create` | `POST /v3/voices/speech` | Generate speech audio from text                    |

### Filter flags for `voice list`

| Flag                | Description                              |
| ------------------- | ---------------------------------------- |
| `--type <type>`     | `public` (default) or `private`          |
| `--engine <engine>` | Filter by voice engine (e.g. `starfish`) |
| `--language <name>` | Filter by language name (e.g. `English`) |
| `--gender <gender>` | `male` or `female`                       |
| `--limit <n>`       | Results per page (1–100, default 20)     |
| `--token <cursor>`  | Pagination cursor                        |

### Flags for `voice create`

| Flag               | Description                                                     |
| ------------------ | --------------------------------------------------------------- |
| `--prompt <text>`  | Natural language description of the desired voice (required)    |
| `--gender <value>` | `male` or `female`                                              |
| `--locale <bcp47>` | BCP-47 locale tag (e.g. `en-US`)                                |
| `--seed <n>`       | Increment to get a different batch of voice results (default 0) |

### Flags for `voice speech create`

| Flag                  | Description                                        |
| --------------------- | -------------------------------------------------- |
| `--text <text>`       | Text to synthesize (required)                      |
| `--voice-id <id>`     | Voice ID to use (required)                         |
| `--speed <n>`         | Playback speed multiplier, `0.5`–`2.0` (default 1) |
| `--language <code>`   | Base language code (auto-detected if omitted)      |
| `--locale <bcp47>`    | BCP-47 locale tag                                  |
| `--input-type <type>` | `text` (default) or `ssml`                         |

## Lipsync

Dub or replace audio on existing videos.

| Command                              | API Endpoint                       | Description                    |
| ------------------------------------ | ---------------------------------- | ------------------------------ |
| `heygen lipsync create`              | `POST /v3/lipsyncs`                | Create a lipsync job           |
| `heygen lipsync list`                | `GET /v3/lipsyncs`                 | List lipsync jobs              |
| `heygen lipsync get <lipsync-id>`    | `GET /v3/lipsyncs/{lipsync_id}`    | Get lipsync details and status |
| `heygen lipsync update <lipsync-id>` | `PATCH /v3/lipsyncs/{lipsync_id}`  | Update a lipsync title         |
| `heygen lipsync delete <lipsync-id>` | `DELETE /v3/lipsyncs/{lipsync_id}` | Delete a lipsync               |

`lipsync create` requires a complex request body (video and audio sources use discriminated unions). Use `-d`:

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

Run `heygen lipsync create --request-schema` to see all available fields.

## Video Translate

Translate videos into other languages with lip-sync.

| Command                                             | API Endpoint                                           | Description                   |
| --------------------------------------------------- | ------------------------------------------------------ | ----------------------------- |
| `heygen video-translate create`                     | `POST /v3/video-translations`                          | Create a video translation    |
| `heygen video-translate list`                       | `GET /v3/video-translations`                           | List translations             |
| `heygen video-translate get <id>`                   | `GET /v3/video-translations/{id}`                      | Get translation details       |
| `heygen video-translate update <id>`                | `PATCH /v3/video-translations/{id}`                    | Update a translation title    |
| `heygen video-translate delete <id>`                | `DELETE /v3/video-translations/{id}`                   | Delete a translation          |
| `heygen video-translate languages list`             | `GET /v3/video-translations/languages`                 | List supported languages      |
| `heygen video-translate proofreads create`          | `POST /v3/video-translations/proofreads`               | Create a proofread session    |
| `heygen video-translate proofreads get <id>`        | `GET /v3/video-translations/proofreads/{id}`           | Get proofread status          |
| `heygen video-translate proofreads generate <id>`   | `POST /v3/video-translations/proofreads/{id}/generate` | Generate video from proofread |
| `heygen video-translate proofreads srt get <id>`    | `GET /v3/video-translations/proofreads/{id}/srt`       | Download proofread SRT        |
| `heygen video-translate proofreads srt update <id>` | `PUT /v3/video-translations/proofreads/{id}/srt`       | Upload edited SRT             |

### Flags for `video-translate create`

| Flag                         | Description                                                                                              |
| ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| `--output-languages <langs>` | Target language names, comma-separated (required). Use `video-translate languages list` for valid values |
| `--mode <mode>`              | `speed` or `precision`                                                                                   |
| `--speaker-num <n>`          | Number of speakers in source (improves separation)                                                       |
| `--translate-audio-only`     | Translate audio without lip-sync                                                                         |
| `--enable-caption`           | Add captions to translated video                                                                         |
| `--input-language <code>`    | Source language code (auto-detected if omitted)                                                          |
| `--callback-url <url>`       | Webhook URL for completion notifications                                                                 |
| `--title <text>`             | Title for the translation job                                                                            |

## Webhooks

Manage webhook endpoints for event notifications.

| Command                                       | API Endpoint                                     | Description                |
| --------------------------------------------- | ------------------------------------------------ | -------------------------- |
| `heygen webhook endpoints create`             | `POST /v3/webhooks/endpoints`                    | Create a webhook endpoint  |
| `heygen webhook endpoints list`               | `GET /v3/webhooks/endpoints`                     | List webhook endpoints     |
| `heygen webhook endpoints update <id>`        | `PATCH /v3/webhooks/endpoints/{id}`              | Update a webhook endpoint  |
| `heygen webhook endpoints delete <id>`        | `DELETE /v3/webhooks/endpoints/{id}`             | Delete a webhook endpoint  |
| `heygen webhook endpoints rotate-secret <id>` | `POST /v3/webhooks/endpoints/{id}/rotate-secret` | Rotate signing secret      |
| `heygen webhook event-types list`             | `GET /v3/webhooks/event-types`                   | List available event types |
| `heygen webhook events list`                  | `GET /v3/webhooks/events`                        | List delivered events      |

### Flags for `webhook endpoints create`

| Flag               | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `--url <url>`      | Publicly accessible HTTPS URL (required)                          |
| `--events <types>` | Comma-separated event types to subscribe to (omit for all events) |
| `--entity-id <id>` | Scope this endpoint to a specific resource                        |

<Info>
  Store the `secret` returned by `endpoints create` and `endpoints rotate-secret` securely — it is used to verify webhook signatures and will not be shown again.
</Info>

## Assets

Upload files for use in video creation.

| Command               | API Endpoint      | Description                      |
| --------------------- | ----------------- | -------------------------------- |
| `heygen asset create` | `POST /v3/assets` | Upload a file to get an asset ID |

### Flags for `asset create`

| Flag            | Description                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--file <path>` | Local file to upload (required). Max 32 MB. Supported types: image (png, jpeg), video (mp4, webm), audio (mp3, wav), pdf |

## User

| Command              | API Endpoint       | Description                                 |
| -------------------- | ------------------ | ------------------------------------------- |
| `heygen user me get` | `GET /v3/users/me` | Get current user info, credits, and billing |

## Authentication

| Command              | Description                                      |
| -------------------- | ------------------------------------------------ |
| `heygen auth login`  | Authenticate interactively (prompts for API key) |
| `heygen auth status` | Verify stored credentials and show account info  |

For CI/Docker, use the `HEYGEN_API_KEY` environment variable instead. It takes precedence over stored credentials.

## Utility Commands

| Command                           | Description                                  |
| --------------------------------- | -------------------------------------------- |
| `heygen config set <key> <value>` | Set a persistent config value                |
| `heygen config get <key>`         | Read a config value                          |
| `heygen config list`              | Show all config values and their sources     |
| `heygen update`                   | Self-update to the latest version            |
| `heygen update --version <tag>`   | Update to a specific version (e.g. `v0.1.0`) |

### Config keys

| Key         | Values          | Description                                 |
| ----------- | --------------- | ------------------------------------------- |
| `output`    | `json`, `human` | Default output format (default: `json`)     |
| `analytics` | `true`, `false` | Enable or disable anonymous usage analytics |