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.
Video Agent
Create videos from text prompts using AI.| Command | API Endpoint | Description |
|---|---|---|
heygen video-agent create <prompt> | POST /v3/video-agents | AI picks avatar, voice, layout from prompt |
heygen video-agent styles | GET /v3/video-agents/styles | List available video styles |
Videos
Create, list, retrieve, and delete avatar videos with full parameter control.| Command | API Endpoint | Description |
|---|---|---|
heygen video create | POST /v3/videos | Create video with explicit avatar, voice, script |
heygen video list | GET /v3/videos | List your videos |
heygen video get <id> | GET /v3/videos/{video_id} | Get video details and status |
heygen video delete <id> | DELETE /v3/videos/{video_id} | Delete a video |
heygen video download <id> | Client-side | Download video file to disk |
Flags for video create
| Flag | Description |
|---|---|
--avatar-id <id> | HeyGen avatar ID (mutually exclusive with --image-url) |
--image-url <url> | Public URL of an image to animate (mutually exclusive with --avatar-id) |
--voice-id <id> | Voice ID for TTS (required when --script is provided) |
--script <text> | Text script for the avatar to speak (use - for stdin) |
--audio-url <url> | Audio file URL for lip-sync (mutually exclusive with --script) |
--aspect-ratio <ratio> | 16:9 or 9:16 |
--resolution <res> | 1080p or 720p |
--title <text> | Display title in the HeyGen dashboard |
--callback-url <url> | Webhook URL for completion notifications |
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 | GET /v3/avatars/looks | List avatar looks |
heygen avatar looks get <look_id> | GET /v3/avatars/looks/{look_id} | Get avatar look details |
Filter flags for avatar looks
| Flag | Description |
|---|---|
--group-id <id> | Filter by avatar group |
--avatar-type <type> | studio_avatar, video_avatar, or photo_avatar |
--ownership <scope> | public or private |
Voices
Browse voices and generate speech audio.| Command | API Endpoint | Description |
|---|---|---|
heygen voice list | GET /v3/voices | List voices |
heygen voice speech <text> | POST /v3/voices/speech | Generate speech audio from text |
Filter flags for voice list
| Flag | Description |
|---|---|
--type <type> | public or private |
--language <name> | Filter by language name (e.g., English) |
--gender <gender> | male or female |
Flags for voice speech
| Flag | Description |
|---|---|
--voice-id <id> | Voice ID (required) |
--speed <n> | Playback speed, 0.5 to 2.0 |
--language <code> | Language code |
--locale <bcp47> | BCP 47 locale tag |
-o, --out <path> | Save audio to file |
Video Translate
Translate videos into other languages with lip-sync.| Command | API Endpoint | Description |
|---|---|---|
heygen translate create | POST /v3/video-translations | Create a video translation |
heygen translate list | GET /v3/video-translations | List translations |
heygen translate get <id> | GET /v3/video-translations/{id} | Get translation details |
heygen translate update <id> | PATCH /v3/video-translations/{id} | Update a translation |
heygen translate delete <id> | DELETE /v3/video-translations/{id} | Delete a translation |
heygen translate caption <id> | GET /v3/video-translations/{id}/caption | Get translation caption |
heygen translate languages | GET /v3/video-translations/languages | List supported languages |
Flags for translate create
| Flag | Description |
|---|---|
--video-url <url> | Source video URL |
--output-language <code> | Target language code (e.g., es) |
--mode <mode> | speed or precision |
--speaker-num <n> | Number of speakers in source |
--translate-audio-only | Translate audio without lip-sync |
--enable-caption | Add captions to translated video |
--callback-url <url> | Webhook URL for completion notifications |
Webhooks
Manage webhook endpoints for event notifications.| Command | API Endpoint | Description |
|---|---|---|
heygen webhook create | POST /v3/webhooks/endpoints | Create a webhook endpoint |
heygen webhook list | GET /v3/webhooks/endpoints | List webhook endpoints |
heygen webhook update <id> | PATCH /v3/webhooks/endpoints/{id} | Update a webhook endpoint |
heygen webhook delete <id> | DELETE /v3/webhooks/endpoints/{id} | Delete a webhook endpoint |
heygen webhook rotate-secret <id> | POST /v3/webhooks/endpoints/{id}/rotate-secret | Rotate signing secret |
heygen webhook event-types | GET /v3/webhooks/event-types | List available event types |
heygen webhook events | GET /v3/webhooks/events | List delivered events |
Assets
Upload files for use in video creation.| Command | API Endpoint | Description |
|---|---|---|
heygen asset upload <file> | POST /v3/assets | Upload a file to get an asset ID |
Authentication
| Command | Description |
|---|---|
heygen auth login --key <key> | Authenticate with an API key |
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 |
heygen update | Self-update to latest version |