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.
Ai Clipping
Turn long-form videos into ready-to-share short clips with captions| Command | API Endpoint | Description |
|---|---|---|
heygen ai-clipping create | POST /v3/ai-clipping | Create AI Clipping |
heygen ai-clipping delete <job-id> | DELETE /v3/ai-clipping/{job_id} | Delete AI Clipping |
heygen ai-clipping get <job-id> | GET /v3/ai-clipping/{job_id} | Get AI Clipping |
heygen ai-clipping list | GET /v3/ai-clipping | List AI Clipping |
Flags for ai-clipping create
| Flag | Description |
|---|---|
--callback-id <value> | Opaque client identifier echoed verbatim in webhook payloads. Mirrors /v3/video-translations callback_id. |
--callback-url <value> | HTTPS URL to receive per-job webhook callbacks. Mirrors /v3/video-translations callback_url. Per-job callback_url deliveries are NOT HMAC-signed: authenticate them by verifying TLS and matching the echoed callback_id, and do not trust an unverified body. To receive a signed payload, register a webhook endpoint with a secret (the signature header is sent only to registered endpoints). |
--input-language <value> | ISO-639-1 source language code (e.g. ‘en’, ‘es’). Omit for auto-detect. |
--title <value> | Title for the job. Defaults to the source video’s title if omitted. |
Flags for ai-clipping list
| Flag | Description |
|---|---|
--limit <n> | Maximum number of items per page. Defaults to 10 (lower than other v3 lists) because each item embeds its full clips array. |
--token <value> | Opaque cursor token for the next page. |
Asset
Upload files for use in video creation| Command | API Endpoint | Description |
|---|---|---|
heygen asset batches get <batch-id> | GET /v3/assets/batches/{batch_id} | Get Asset Batch |
heygen asset complete batches create | POST /v3/assets/complete/batches | Complete Asset Upload Batch |
heygen asset complete create <asset-id> | POST /v3/assets/{asset_id}/complete | Complete Asset Upload |
heygen asset create | POST /v3/assets | Upload Asset |
heygen asset delete <asset-id> | DELETE /v3/assets/{asset_id} | Delete Asset |
heygen asset direct-uploads batches create | POST /v3/assets/direct-uploads/batches | Create Asset Upload Batch |
heygen asset direct-uploads create | POST /v3/assets/direct-uploads | Create Asset Upload |
heygen asset get <asset-id> | GET /v3/assets/{asset_id} | Get Asset |
heygen asset list | GET /v3/assets | List Assets |
heygen asset statuses list | GET /v3/assets/statuses | Bulk Asset Statuses |
Flags for asset batches get
| Flag | Description |
|---|---|
--limit <n> | Items per page (1-100). |
--token <value> | Opaque pagination cursor from a previous response. |
Flags for asset complete batches create
| Flag | Description |
|---|---|
--batch-id <value> | Identifier returned by POST /v3/assets/direct-uploads/batches. (required) |
Flags for asset complete create
| Flag | Description |
|---|---|
--checksum-sha-256 <value> | Optional SHA256 (hex) cross-check. |
Flags for asset create
| Flag | Description |
|---|---|
--file <value> | File to upload (image, video, audio, PDF, or SRT subtitle). Max 32 MB. (required) |
Flags for asset direct-uploads batches create
| Flag | Description |
|---|---|
--callback-url <value> | Reserved. Asset completion does not emit a webhook. |
--title <value> | Display name for the batch, shown in the HeyGen app. |
Flags for asset direct-uploads create
| Flag | Description |
|---|---|
--checksum-sha-256 <value> | Optional SHA256 of the file as hex. When provided, S3 enforces it on upload. |
--content-type <value> | Declared MIME type (e.g. ‘video/mp4’, ‘image/png’, ‘audio/mpeg’, ‘application/pdf’, ‘application/zip’). Verified against the stored bytes at completion. (required) |
--filename <value> | Original filename for reference/metadata. The stored object’s extension is derived from content_type. (required) |
--size-bytes <n> | Exact byte size of the file. Signed into the upload URL so it cannot be exceeded. (required) |
Flags for asset list
| Flag | Description |
|---|---|
--username <value> | Username of the workspace member whose assets to list — the same value as asset items’ ‘owner’ field. Required while this endpoint is in beta; it will become an optional filter in a future release. (required) |
--limit <n> | Maximum number of assets to return per page (1-100). |
--token <value> | Opaque cursor from a previous response’s next_token. Omit for the first page. |
--folder-id <value> | Optional folder filter. Omit to list ALL workspace assets across folders. Pass a folder id to list that folder only, or an empty value (folder_id=) for root-level assets (assets not filed into any folder). |
Flags for asset statuses list
| Flag | Description |
|---|---|
--asset-ids <value> | Comma-separated asset ids to look up. |
--batch-ids <value> | Comma-separated batch ids; each expands to its member assets. |
Audio
Search the background-music and sound-effects catalog| Command | API Endpoint | Description |
|---|---|---|
heygen audio sounds list | GET /v3/audio/sounds | Search audio (music or sound effects) |
Flags for audio sounds list
| Flag | Description |
|---|---|
--query <value> | Natural-language description of the audio you want, e.g. ‘upbeat lofi hip-hop’ or ‘tense cinematic riser’. Results are ranked by semantic similarity to this text. (required) |
--type <value> | Audio content type to search: ‘music’ (background-music catalog) or ‘sound_effects’ (SFX catalog). Defaults to ‘music’. |
--limit <n> | Maximum number of results to return (1-50). |
--min-score <n> | Minimum semantic similarity score (0-1). Tracks scoring below this are omitted. |
--token <value> | Opaque cursor token for the next page, taken from ‘next_token’ in a prior response. |
Avatar
List and manage avatars and looks| Command | API Endpoint | Description |
|---|---|---|
heygen avatar consent create <group-id> | POST /v3/avatars/{group_id}/consent | Create Avatar Consent |
heygen avatar create | POST /v3/avatars | Create Avatar |
heygen avatar delete <group-id> | DELETE /v3/avatars/{group_id} | Delete Avatar Group |
heygen avatar get <group-id> | GET /v3/avatars/{group_id} | Get Avatar Group |
heygen avatar list | GET /v3/avatars | List Avatar Groups |
heygen avatar looks delete <look-id> | DELETE /v3/avatars/looks/{look_id} | Delete Avatar Look |
heygen avatar looks get <look-id> | GET /v3/avatars/looks/{look_id} | Get Avatar Look |
heygen avatar looks list | GET /v3/avatars/looks | List Avatar Looks |
heygen avatar looks update <look-id> | PATCH /v3/avatars/looks/{look_id} | Update Avatar Look |
Flags for avatar consent create
| Flag | Description |
|---|---|
--reroute-url <value> | Callback URL where the user is redirected after completing consent. Defaults to HeyGen’s consent completion page. |
Flags for avatar create
This command takes a structured request body. Pass it with -d and run the command with --request-schema to see all fields.
Flags for avatar list
| Flag | Description |
|---|---|
--ownership <value> | Filter by ownership: ‘public’ for preset avatars, or ‘private’ for your own. Omit for all. |
--limit <n> | Maximum number of items to return per page (1-50). |
--token <value> | Opaque cursor token for the next page. |
Flags for avatar looks list
| Flag | Description |
|---|---|
--group-id <value> | Filter looks to a specific avatar group. Returns only looks belonging to this group. |
--avatar-type <value> | Filter by avatar type: ‘studio_avatar’, ‘digital_twin’, or ‘photo_avatar’. |
--ownership <value> | Filter by ownership: ‘public’ for preset avatars, or ‘private’ for your own. Omit for all. |
--limit <n> | Maximum number of items to return per page (1-50). |
--token <value> | Opaque cursor token for the next page. |
Flags for avatar looks update
| Flag | Description |
|---|---|
--name <value> | New display name for the look. |
Background Removal
| Command | API Endpoint | Description |
|---|---|---|
heygen background-removal create | POST /v3/background-removals | Create Background Removal |
heygen background-removal delete <job-id> | DELETE /v3/background-removals/{job_id} | Delete Background Removal |
heygen background-removal get <job-id> | GET /v3/background-removals/{job_id} | Get Background Removal |
heygen background-removal list | GET /v3/background-removals | List Background Removals |
Flags for background-removal create
| Flag | Description |
|---|---|
--layers <values> | Output layers to return. Any of: ‘foreground’ (subject on a transparent background), ‘mask’ (grayscale alpha matte), ‘background’ (the scene with the subject removed). Defaults to all three. |
--request-id <value> | Client-provided idempotency key — the idempotency mechanism for this endpoint. Re-sending the same request_id returns the original job (same id, same status, same charge) instead of creating a new one — the dedup is over (space_id, request_id), not over the response body, so a duplicate request_id with different content still collides on the original job. The HTTP Idempotency-Key header is not honored here; pick a per-content request_id if you need per-content dedup. |
--title <value> | Optional human-readable title for the job. |
Flags for background-removal list
| Flag | Description |
|---|---|
--limit <n> | Maximum number of jobs to return (1-100). |
--token <value> | Opaque pagination cursor from a previous response’s next_token. |
Brand
Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations)| Command | API Endpoint | Description |
|---|---|---|
heygen brand glossaries create | POST /v3/brand-glossaries | Create Brand Glossary |
heygen brand glossaries get <brand-glossary-id> | GET /v3/brand-glossaries/{brand_glossary_id} | Get Brand Glossary |
heygen brand glossaries list | GET /v3/brand-glossaries | List Brand Glossaries |
heygen brand glossaries update <brand-glossary-id> | PATCH /v3/brand-glossaries/{brand_glossary_id} | Update Brand Glossary |
heygen brand kits create | POST /v3/brand-kits | Create Brand Kit |
heygen brand kits get <brand-kit-id> | GET /v3/brand-kits/{brand_kit_id} | Get Brand Kit |
heygen brand kits list | GET /v3/brand-kits | List Brand Kits |
Flags for brand glossaries create
| Flag | Description |
|---|---|
--name <value> | Display name for the glossary. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case. (required) |
Flags for brand glossaries list
| Flag | Description |
|---|---|
--limit <n> | Maximum number of brand glossaries to return (1-100). Default 10. |
--token <value> | Opaque pagination cursor from a previous response’s next_token. Omit for the first page. |
Flags for brand glossaries update
| Flag | Description |
|---|---|
--name <value> | New display name. Surrounding whitespace is removed, and the trimmed name must be 1-64 characters and unique within your workspace, compared without regard to case. Omit to keep the current name. |
Flags for brand kits create
| Flag | Description |
|---|---|
--name <value> | Name for the brand kit, up to 256 characters. Defaults to the brand name detected on the site, or its domain. |
--url <value> | Public website URL to build the brand kit from. HeyGen visits the site and imports the brand assets it finds there, including logos, colors and font files. By calling this endpoint you confirm you have the rights and licenses necessary to upload, store and use those assets in HeyGen. (required) |
Flags for brand kits list
| Flag | Description |
|---|---|
--limit <n> | Results per page (1-100). |
--token <value> | Opaque cursor token for the next page. Obtained from next_token in a previous response. |
Filler Word Removal
| Command | API Endpoint | Description |
|---|---|---|
heygen filler-word-removal create | POST /v3/filler-word-removals | Create Filler Word Removal |
heygen filler-word-removal get <filler-word-removal-id> | GET /v3/filler-word-removals/{filler_word_removal_id} | Get Filler Word Removal |
Flags for filler-word-removal create
| Flag | Description |
|---|---|
--callback-id <value> | Opaque client identifier echoed verbatim in webhook payloads. |
--callback-url <value> | HTTPS URL to receive per-job webhook callbacks (filler_word_removal.success / filler_word_removal.fail). Delivery is best-effort with limited retries — poll GET /v3/filler-word-removals/ as the source of truth (a terminal GET may precede its webhook). Per-job callback_url deliveries are NOT HMAC-signed: authenticate them by verifying TLS and matching the echoed callback_id, and do not trust an unverified body. To receive a signed payload, register a webhook endpoint with a secret via /v3/webhooks/endpoints. |
--title <value> | Display title for the job. Defaults to ‘Filler Removal’ if omitted. |
Lipsync
Dub or replace audio on existing videos| Command | API Endpoint | Description |
|---|---|---|
heygen lipsync batches create | POST /v3/lipsyncs/batches | Create Lipsync Batch |
heygen lipsync batches get <batch-id> | GET /v3/lipsyncs/batches/{batch_id} | Get Lipsync Batch |
heygen lipsync create | POST /v3/lipsyncs | Create Lipsync |
heygen lipsync delete <lipsync-id> | DELETE /v3/lipsyncs/{lipsync_id} | Delete Lipsync |
heygen lipsync get <lipsync-id> | GET /v3/lipsyncs/{lipsync_id} | Get Lipsync |
heygen lipsync list | GET /v3/lipsyncs | List Lipsyncs |
heygen lipsync statuses list | GET /v3/lipsyncs/statuses | Bulk Lipsync Statuses |
heygen lipsync update <lipsync-id> | PATCH /v3/lipsyncs/{lipsync_id} | Update Lipsync |
Flags for lipsync batches create
| Flag | Description |
|---|---|
--callback-url <value> | Webhook URL invoked once when every item in the batch reaches a terminal state. |
--title <value> | Display name for the batch, shown in the HeyGen app. |
Flags for lipsync batches get
| Flag | Description |
|---|---|
--limit <n> | Items per page (1-100). |
--token <value> | Opaque pagination cursor from a previous response. |
Flags for lipsync create
| Flag | Description |
|---|---|
--callback-id <value> | ID included in webhook payload |
--callback-url <value> | Webhook URL for completion notifications |
--disable-music-track | Remove background music |
--enable-caption | Deprecated and ignored: captions are always generated; whether to display them is a download-side choice. |
--enable-dynamic-duration | Allow dynamic duration adjustment |
--enable-speech-enhancement | Enhance speech quality |
--enable-watermark | Add watermark to output |
--end-time <n> | End time in seconds for partial lipsync |
--folder-id <value> | Project/folder ID to organize lipsync into |
--fps-mode <value> | Frame rate mode: ‘vfr’, ‘cfr’, or ‘passthrough’. |
--keep-the-same-format | Preserve the source video’s encoding specs (resolution, bitrate). |
--mode <value> | Quality mode: ‘speed’ (faster) or ‘precision’ (higher quality, uses avatar inference) |
--start-time <n> | Start time in seconds for partial lipsync |
--title <value> | Title for the lipsync job |
Flags for lipsync list
| Flag | Description |
|---|---|
--limit <n> | Maximum number of items per page |
--token <value> | Opaque cursor token for the next page |
Flags for lipsync statuses list
| Flag | Description |
|---|---|
--lipsync-ids <value> | Comma-separated lipsync ids to look up. |
--batch-ids <value> | Comma-separated batch ids; each expands to its member lipsyncs. |
Flags for lipsync update
| Flag | Description |
|---|---|
--title <value> | New title for the lipsync (required) |
Template
Generate videos from reusable templates by replacing their variables| Command | API Endpoint | Description |
|---|---|---|
heygen template generate <template-id> | POST /v3/templates/{template_id} | Generate Video from Template |
heygen template get <template-id> | GET /v3/templates/{template_id} | Get Template |
heygen template list | GET /v3/templates | List Templates |
Flags for template generate
| Flag | Description |
|---|---|
--brand-glossary-id <value> | Brand glossary controlling how custom terms are pronounced in generated speech. Discover IDs via GET /v3/brand-glossaries. |
--brand-voice-id <value> | Legacy field name for brand_glossary_id. Both are accepted and resolve to the same workspace record. Prefer brand_glossary_id. |
--callback-id <value> | Opaque ID echoed back in webhook events for this video |
--callback-url <value> | URL called with the video result in addition to registered webhook endpoints |
--caption | Whether to burn captions into the video |
--enable-sharing | Whether the generated video’s share page is publicly accessible |
--folder-id <value> | Folder to place the generated video in |
--fps <n> | Output frame rate. One of 25, 30, or 60. |
--include-gif | Whether to include a GIF preview in the webhook payload |
--keep-text-vertically-centered | When true, replaced text elements are vertically re-centered based on their rendered height |
--reorder-music | When true (default), background audio tracks move with their scenes. When false, tracks stay pinned to layout positions. |
--scene-ids <values> | Scene IDs to render, in order (repeats allowed). Scenes must already exist in the template; the API can select, reorder, and repeat scenes but cannot create new ones. Omit to render all scenes in template order. |
--title <value> | Title for the generated video |
Flags for template list
| Flag | Description |
|---|---|
--limit <n> | Maximum number of templates to return per page |
--token <value> | Opaque pagination token from a previous response’s next_token |
User
Account information and billing| Command | API Endpoint | Description |
|---|---|---|
heygen user me get | GET /v3/users/me | Get Current User |
Video
Create, list, retrieve, and delete videos| Command | API Endpoint | Description |
|---|---|---|
heygen video batches create | POST /v3/videos/batches | Create Video Batch |
heygen video batches get <batch-id> | GET /v3/videos/batches/{batch_id} | Get Video Batch |
heygen video create | POST /v3/videos | Create Video |
heygen video delete <video-id> | DELETE /v3/videos/{video_id} | Delete Video |
heygen video get <video-id> | GET /v3/videos/{video_id} | Get Video |
heygen video list | GET /v3/videos | List Videos |
heygen video statuses list | GET /v3/videos/statuses | Bulk Video Statuses |
Flags for video batches create
| Flag | Description |
|---|---|
--callback-url <value> | Webhook URL invoked once when every item in the batch reaches a terminal state. |
--title <value> | Display name for the batch, shown in the HeyGen app. |
Flags for video batches get
| Flag | Description |
|---|---|
--limit <n> | Items per page (1-100). |
--token <value> | Opaque pagination cursor from a previous response. |
Flags for video create
This command takes a structured request body. Pass it with -d and run the command with --request-schema to see all fields.
Flags for video list
| Flag | Description |
|---|---|
--limit <n> | Maximum number of items to return per page |
--token <value> | Opaque pagination cursor from a previous response |
--folder-id <value> | Filter videos by folder ID |
--title <value> | Filter videos by title substring |
Flags for video statuses list
| Flag | Description |
|---|---|
--video-ids <value> | Comma-separated video ids to look up. |
--batch-ids <value> | Comma-separated batch ids; each expands to its member videos. |
Video Agent
Create videos from text prompts using AI| Command | API Endpoint | Description |
|---|---|---|
heygen video-agent create | POST /v3/video-agents | Create Video Agent Session |
heygen video-agent get <session-id> | GET /v3/video-agents/{session_id} | Get Video Agent Session |
heygen video-agent list | GET /v3/video-agents | List Video Agent Sessions |
heygen video-agent resources get <session-id> <resource-id> | GET /v3/video-agents/{session_id}/resources/{resource_id} | Get Session Resource |
heygen video-agent send <session-id> | POST /v3/video-agents/{session_id} | Send Message or Request Revision |
heygen video-agent stop <session-id> | POST /v3/video-agents/{session_id}/stop | Stop Video Agent Session |
heygen video-agent styles list | GET /v3/video-agents/styles | List Video Agent Styles |
heygen video-agent videos list <session-id> | GET /v3/video-agents/{session_id}/videos | List Session Videos |
Flags for video-agent create
| Flag | Description |
|---|---|
--avatar-id <value> | Specific avatar ID to use |
--brand-kit-id <value> | Brand kit ID to apply brand colors, fonts, and logos to the generated video. |
--callback-id <value> | Optional callback ID included in webhook payload |
--callback-url <value> | Webhook URL for completion/failure notifications |
--incognito-mode | When enabled, disables memory injection and extraction for this session |
--mode <value> | Session mode. ‘generate’ produces one video (fire-and-forget). ‘chat’ enables multi-turn interaction — the agent may pause for decisions and allows revisions. |
--orientation <value> | Video orientation. If not provided, auto-detected from content. |
--prompt <value> | The message/prompt for video generation (1-10000 characters) (required) |
--style-id <value> | Style ID from GET /v3/video-agents/styles. Applies a curated visual template to the generated video. |
--voice-id <value> | Specific voice ID to use for narration |
Flags for video-agent list
| Flag | Description |
|---|---|
--limit <n> | Results per page (1-100). |
--token <value> | Opaque cursor token for the next page. Obtained from next_token in a previous response. |
Flags for video-agent send
| Flag | Description |
|---|---|
--avatar-id <value> | Override avatar for this message |
--brand-kit-id <value> | Brand kit ID to apply for this message |
--message <value> | Text message to the agent (required) |
--voice-id <value> | Override voice for this message |
Flags for video-agent stop
This command takes a structured request body. Pass it with -d and run the command with --request-schema to see all fields.
Flags for video-agent styles list
| Flag | Description |
|---|---|
--tag <value> | Filter by tag (e.g., ‘cinematic’, ‘retro-tech’, ‘iconic-artist’, ‘pop-culture’, ‘handmade’, ‘print’). |
--limit <n> | Results per page (1-100). |
--token <value> | Opaque cursor token for the next page. Obtained from next_token in a previous response. |
Video Translate
Translate videos into other languages| Command | API Endpoint | Description |
|---|---|---|
heygen video-translate batches create | POST /v3/video-translations/batches | Create Video Translation Batch |
heygen video-translate batches get <batch-id> | GET /v3/video-translations/batches/{batch_id} | Get Video Translation Batch |
heygen video-translate create | POST /v3/video-translations | Create Video Translation |
heygen video-translate delete <video-translation-id> | DELETE /v3/video-translations/{video_translation_id} | Delete Video Translation |
heygen video-translate get <video-translation-id> | GET /v3/video-translations/{video_translation_id} | Get Video Translation |
heygen video-translate languages list | GET /v3/video-translations/languages | List Supported Translation Languages |
heygen video-translate list | GET /v3/video-translations | List Video Translations |
heygen video-translate proofreads create | POST /v3/video-translations/proofreads | Create Proofread Session |
heygen video-translate proofreads generate <proofread-id> | POST /v3/video-translations/proofreads/{proofread_id}/generate | Generate Video from Proofread |
heygen video-translate proofreads get <proofread-id> | GET /v3/video-translations/proofreads/{proofread_id} | Get Proofread Session |
heygen video-translate proofreads srt get <proofread-id> | GET /v3/video-translations/proofreads/{proofread_id}/srt | Download Proofread SRT |
heygen video-translate proofreads srt update <proofread-id> | PUT /v3/video-translations/proofreads/{proofread_id}/srt | Upload Proofread SRT |
heygen video-translate statuses list | GET /v3/video-translations/statuses | Bulk Video Translation Statuses |
heygen video-translate update <video-translation-id> | PATCH /v3/video-translations/{video_translation_id} | Update Video Translation |
Flags for video-translate batches create
| Flag | Description |
|---|---|
--callback-url <value> | Webhook URL invoked once when every item in the batch reaches a terminal state. |
--title <value> | Display name for the batch, shown in the HeyGen app. |
Flags for video-translate batches get
| Flag | Description |
|---|---|
--limit <n> | Items per page (1-100). |
--token <value> | Opaque pagination cursor from a previous response. |
Flags for video-translate create
| Flag | Description |
|---|---|
--brand-glossary-id <value> | Brand glossary ID for custom term translations (e.g. translate ‘Reformer’ as the Pilates equipment, not ‘political activist’). Alias for the legacy brand_voice_id field. Discover IDs via GET /v3/brand-glossaries. |
--brand-voice-id <value> | Brand glossary ID for custom term translations. Legacy field name for brand_glossary_id — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries. |
--callback-id <value> | ID included in webhook payload |
--callback-url <value> | Webhook URL for completion notifications |
--disable-music-track | Remove background music |
--enable-caption | Deprecated and ignored: captions are always generated; whether to display them is a download-side choice. |
--enable-dynamic-duration | Allow dynamic duration adjustment |
--enable-speech-enhancement | Enhance speech quality |
--enable-watermark | Add watermark to output |
--end-time <n> | End time in seconds for partial translation |
--folder-id <value> | Project/folder ID to organize translation into |
--fps-mode <value> | Frame rate mode for the output video. ‘vfr’ = variable frame rate, ‘cfr’ = constant frame rate, ‘passthrough’ = match the source. Only takes effect when a custom ‘audio’ track is provided. |
--input-language <value> | Source language code (auto-detected if omitted) |
--keep-the-same-format | Preserve the source video’s encoding specs (resolution, bitrate). |
--mode <value> | Translation quality mode: ‘speed’ (faster) or ‘precision’ (higher quality, uses avatar inference) |
--output-languages <values> | Target language names (e.g. ‘Chinese (Cantonese, Traditional)’, ‘Spanish (Spain)’, ‘English’). Use GET /v3/video-translations/languages for valid values. Use one for single translation, multiple for batch. (required) |
--speaker-num <n> | Number of speakers (improves speaker separation) |
--srt-role <value> | Which video the subtitle applies to: ‘input’ (source) or ‘output’ (translated). |
--start-time <n> | Start time in seconds for partial translation |
--title <value> | Title for the translation job |
--translate-audio-only | Only translate audio, keep original video |
Flags for video-translate list
| Flag | Description |
|---|---|
--limit <n> | Maximum number of items per page |
--token <value> | Opaque cursor token for the next page |
Flags for video-translate proofreads create
| Flag | Description |
|---|---|
--brand-glossary-id <value> | Brand glossary ID for custom term translations (e.g. translate ‘Reformer’ as ‘Pilates equipment’, not ‘political activist’). Alias for the legacy brand_voice_id field. Discover IDs via GET /v3/brand-glossaries. |
--brand-voice-id <value> | Brand glossary ID for custom term translations. Legacy field name for brand_glossary_id — both are accepted and resolve to the same workspace record. Discover IDs via GET /v3/brand-glossaries. |
--disable-music-track | Remove background music |
--enable-speech-enhancement | Enhance speech quality |
--enable-video-stretching | Allow dynamic duration adjustment |
--folder-id <value> | Project/folder ID to organize proofread into |
--keep-the-same-format | Preserve the source video’s encoding specs (resolution, bitrate) |
--mode <value> | Translation quality mode: ‘speed’ (faster) or ‘precision’ (higher quality) |
--output-languages <values> | Target language codes. Use one for single proofread, multiple for batch. (required) |
--speaker-num <n> | Number of speakers (improves speaker separation) |
--title <value> | Title for the proofread job (required) |
Flags for video-translate proofreads generate
| Flag | Description |
|---|---|
--callback-id <value> | ID included in webhook payload |
--callback-url <value> | Webhook URL for completion notifications |
--captions | Deprecated and ignored: captions are always generated; whether to display them is a download-side choice. |
--translate-audio-only | Only translate audio, keep original video |
Flags for video-translate proofreads srt update
This command takes a structured request body. Pass it with -d and run the command with --request-schema to see all fields.
Flags for video-translate statuses list
| Flag | Description |
|---|---|
--video-translation-ids <value> | Comma-separated video translation ids to look up. |
--batch-ids <value> | Comma-separated batch ids; each expands to its member video translations. |
Flags for video-translate update
| Flag | Description |
|---|---|
--title <value> | New title for the video translation (required) |
Voice
Create speech audio and manage voices| Command | API Endpoint | Description |
|---|---|---|
heygen voice clone create | POST /v3/voices/clone | Clone a Voice |
heygen voice create | POST /v3/voices | Design a Voice |
heygen voice delete <voice-id> | DELETE /v3/voices/{voice_id} | Delete a Voice |
heygen voice get <voice-id> | GET /v3/voices/{voice_id} | Get Voice |
heygen voice list | GET /v3/voices | List Voices |
heygen voice speech create | POST /v3/voices/speech | Generate Speech |
Flags for voice clone create
| Flag | Description |
|---|---|
--language <value> | Language hint for the voice (e.g., ‘en’, ‘es’). Auto-detected if omitted. |
--remove-background-noise | Remove background noise from the audio before cloning. |
--voice-name <value> | Display name for the cloned voice. (required) |
Flags for voice create
| Flag | Description |
|---|---|
--gender <value> | Filter by gender: ‘male’ or ‘female’. |
--locale <value> | BCP-47 locale tag to filter by (e.g., ‘en-US’, ‘pt-BR’). |
--prompt <value> | Natural language description of the desired voice (e.g., ‘warm, confident female narrator’). (required) |
--seed <n> | Controls which batch of results to return. seed=0 returns the top matches, seed=1 the next batch, etc. Same prompt + seed always returns the same voices. |
Flags for voice list
| Flag | Description |
|---|---|
--type <value> | Voice type: ‘public’ for the shared library or ‘private’ for your cloned voices. |
--engine <value> | Filter by voice engine (e.g. ‘starfish’). When set, only voices compatible with that engine are returned. |
--language <value> | Filter by language (e.g. ‘English’). |
--gender <value> | Filter by gender (‘male’ or ‘female’). |
--limit <n> | Results per page (1-100). |
--token <value> | Opaque cursor token for the next page. |
Flags for voice speech create
| Flag | Description |
|---|---|
--input-type <value> | Type of the input: ‘text’ for plain text, ‘ssml’ for SSML markup. Defaults to ‘text’. |
--language <value> | Base language code (e.g. ‘en’, ‘pt’, ‘zh’). Optional — auto-detected from text when omitted. |
--locale <value> | BCP-47 locale tag (e.g. ‘en-US’, ‘pt-BR’). When set, language is inferred from locale. |
--speed <n> | Speed multiplier (0.5-2.0). |
--text <value> | Text to synthesize (1-5000 characters). Break tags must express time in seconds (for example, |
--voice-id <value> | Voice ID to use. The voice must support the starfish engine. Filter compatible voices by passing engine=starfish to the voice listing endpoint. (required) |
Webhook
Create, list, and manage webhook endpoints and events| Command | API Endpoint | Description |
|---|---|---|
heygen webhook endpoints create | POST /v3/webhooks/endpoints | Create Webhook Endpoint |
heygen webhook endpoints delete <endpoint-id> | DELETE /v3/webhooks/endpoints/{endpoint_id} | Delete Webhook Endpoint |
heygen webhook endpoints list | GET /v3/webhooks/endpoints | List Webhook Endpoints |
heygen webhook endpoints rotate-secret <endpoint-id> | POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret | Rotate Webhook Signing Secret |
heygen webhook endpoints update <endpoint-id> | PATCH /v3/webhooks/endpoints/{endpoint_id} | Update Webhook Endpoint |
heygen webhook event-types list | GET /v3/webhooks/event-types | List Webhook Event Types |
heygen webhook events list | GET /v3/webhooks/events | List Webhook Events |
Flags for webhook endpoints create
| Flag | Description |
|---|---|
--entity-id <value> | Optional entity ID to scope this endpoint to a specific resource (e.g. a personalized video project). |
--events <values> | Event types to subscribe to. Omit or set to null to receive all events. |
--url <value> | Publicly accessible HTTPS URL that will receive webhook POST requests. (required) |
Flags for webhook endpoints list
| Flag | Description |
|---|---|
--limit <n> | Maximum number of endpoints to return (1-100). Default: 10. |
--token <value> | Opaque pagination cursor from a previous response’s next_token. |
Flags for webhook endpoints update
| Flag | Description |
|---|---|
--events <values> | New list of event types to subscribe to. Replaces the existing list. |
--url <value> | New URL for the endpoint. Must be publicly accessible HTTPS. |
Flags for webhook events list
| Flag | Description |
|---|---|
--event-type <value> | Filter events by type, e.g. ‘avatar_video.success’. |
--entity-id <value> | Filter events by entity ID. |
--limit <n> | Maximum number of events to return (1-100). Default: 10. |
--token <value> | Opaque pagination cursor from a previous response’s next_token. |
Authentication
| Command | Description |
|---|---|
heygen auth login | Authenticate interactively (prompts for API key) |
heygen auth login --oauth | Log in via browser OAuth — uses subscription credits (free usage) |
heygen auth status | Verify stored credentials and show account info |
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 |