Commands - HeyGen Documentation

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:

# 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"
}'

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

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

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.

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:

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

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.

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

Documentation Index

​Video Agent

​Flags for video-agent create

​Videos

​Flags for video create

​Flags for video list

​Flags for video download

​Avatars

​Filter flags for avatar list

​Filter flags for avatar looks list

​Voices

​Filter flags for voice list

​Flags for voice create

​Flags for voice speech create

​Lipsync

​Video Translate

​Flags for video-translate create

​Webhooks

​Flags for webhook endpoints create

​Assets

​Flags for asset create

​User

​Authentication

​Utility Commands

​Config keys

Video Agent

Flags for `video-agent create`

Videos

Flags for `video create`

Flags for `video list`

Flags for `video download`

Avatars

Filter flags for `avatar list`

Filter flags for `avatar looks list`

Voices

Filter flags for `voice list`

Flags for `voice create`

Flags for `voice speech create`

Lipsync

Video Translate

Flags for `video-translate create`

Webhooks

Flags for `webhook endpoints create`

Assets

Flags for `asset create`

User

Authentication

Utility Commands

Config keys