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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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 look-templates list | GET /v3/avatars/look-templates | List Look Templates |
heygen avatar looks create | POST /v3/avatars/looks | Create Avatar Looks |
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 |
heygen avatar update <group-id> | PATCH /v3/avatars/{group_id} | Update Avatar Group |
Flags for avatar consent create
| Flag | Description |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--reroute-url <value> | Callback URL where the user is redirected after completing consent. Defaults to HeyGen’s consent completion page. |
Flags for avatar create
| Flag | Description |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
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 look-templates list
| Flag | Description |
|---|---|
--type <value> | Filter by generation method: ‘look_pack’ for Look Packs, ‘template’ for single look templates. Omit for both. |
--gender <value> | Filter to templates built for ‘male’ or ‘female’. Templates with no gender of their own are returned for either value. 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 create
| Flag | Description |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
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. |
Flags for avatar update
| Flag | Description |
|---|---|
--default-voice-id <value> | Voice ID to set as the avatar’s default voice, replacing the current one. The voice is also linked to the avatar group if it was not already. Accepts any voice available to your workspace, including imported voice clones. Only supported for avatars you own. |
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 delete <brand-glossary-id> | DELETE /v3/brand-glossaries/{brand_glossary_id} | Delete 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 delete <brand-kit-id> | DELETE /v3/brand-kits/{brand_kit_id} | Delete 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 |
heygen brand kits update <brand-kit-id> | PATCH /v3/brand-kits/{brand_kit_id} | Update Brand Kit |
Flags for brand glossaries create
| Flag | Description |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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. |
Flags for brand kits update
| Flag | Description |
|---|---|
--name <value> | New display name for the brand kit, 1-256 characters. Leading and trailing whitespace is trimmed. |
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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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/{id} 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. |
Folder
Create folders to organize videos and translations in the workspace| Command | API Endpoint | Description |
|---|---|---|
heygen folder create | POST /v3/folders | Create Folder |
heygen folder get <folder-id> | GET /v3/folders/{folder_id} | Get Folder |
Flags for folder create
| Flag | Description |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--name <value> | Folder name, 1-256 characters. Sibling folders may share a name. (required) |
--parent-id <value> | ID of the folder to create this one in. Omit, pass null, or pass an empty string to create it at the workspace root. The parent must be a folder in the caller’s workspace that is not in the trash. |
--type <value> | Kind of folder. ‘mixed’ is what the HeyGen web app’s New folder action creates; ‘video_translate’ is what the Video Translate page creates. The web app lists all three kinds together in its folder views, and every kind accepts videos and translations placed with folder_id on POST /v3/videos and POST /v3/video-translations. |
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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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> | Destination folder ID in the caller’s workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. |
--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) |
Model
| Command | API Endpoint | Description |
|---|---|---|
heygen model audio tts create | POST /v3/models/audio/tts | Generate Speech |
heygen model audio voices create | POST /v3/models/audio/voices | Create or Retrain an Audio Voice |
heygen model audio voices delete <voice-id> | DELETE /v3/models/audio/voices/{voice_id} | Delete an Audio Voice |
heygen model audio voices get <voice-id> | GET /v3/models/audio/voices/{voice_id} | Get an Audio Voice |
heygen model audio voices list | GET /v3/models/audio/voices | List Audio Voices |
Flags for model audio tts create
| Flag | Description |
|---|---|
--language <value> | Language code used for speech synthesis, such as en. (required) |
--pitch-shift <n> | Pitch shift in semitones. |
--pitch-variance <n> | Pitch variation multiplier; 1.0 preserves the voice default. |
--seed <n> | Optional best-effort deterministic generation seed. |
--speed <n> | Speech speed multiplier. |
--text <value> | Plain text to synthesize. SSML and break tags are not supported. (required) |
--voice-id <value> | Identifier of the voice used for speech synthesis. (required) |
Flags for model audio voices create
| Flag | Description |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--language <value> | Primary language code, such as en, for a new voice. Ignored when voice_id is supplied; the existing language is retained. |
--mode <value> | Voice operation mode for a new voice. Ignored when voice_id is supplied; the existing mode is retained. Currently only professional is supported. |
--name <value> | Display name for a new voice. Ignored when voice_id is supplied; the existing name is retained. |
--voice-id <value> | Existing professional voice to retrain. Omit to create a new voice. |
Flags for model audio voices list
| Flag | Description |
|---|---|
--limit <n> | Maximum number of voices to return per page. |
--token <value> | Opaque pagination token returned by a previous request. |
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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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> | Destination folder ID in the caller’s workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. Supported only for single-video creation; batch video items cannot set their own destination folder. |
--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 scenes get <video-id> | GET /v3/videos/{video_id}/scenes | Get Video Scenes |
heygen video statuses list | GET /v3/videos/statuses | Bulk Video Statuses |
Flags for video batches create
| Flag | Description |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--callback-url <value> | Webhook URL invoked once when every item in the batch reaches a terminal state. |
--folder-id <value> | Destination folder ID for the batch container. The videos remain grouped inside the newly created batch; the batch itself is placed in this folder. Omit, pass null, or pass an empty string to place the batch at the workspace root. |
--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
| Flag | Description |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
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 Video Agent Message |
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-glossary-id <value> | Brand glossary ID controlling how custom terms are pronounced in the generated video’s narration (for example, saying ‘HeyGen’ as ‘hey-jen’). Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries. |
--brand-kit-id <value> | Brand kit ID to apply brand colors, fonts, and logos to the generated video. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted; omit this field to apply the workspace default automatically. |
--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 |
--members <values> | Email addresses to grant access to. Valid only with visibility: selected, and every address must belong to a member of the caller’s workspace (max 100). May be omitted or empty, leaving the session owner-only until members are added. |
--mode <value> | Session mode. ‘generate’ produces one video (fire-and-forget). ‘chat’ enables multi-turn interaction — the agent may pause for decisions and accept follow-up messages. |
--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. |
--visibility <value> | Who can open the session. private: the owner only. space: everyone in the workspace can open and drive the session. selected: the owner plus the workspace members listed in members. Defaults to space. Applies to the session and its conversation; does not change existing sessions. |
--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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--avatar-id <value> | Override avatar for this message |
--brand-kit-id <value> | Brand kit ID to apply for this message. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted. |
--message <value> | Text message to the agent. Required when edit_plan is omitted; may be omitted or empty when edit_plan is provided. |
--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 delete <proofread-id> | DELETE /v3/video-translations/proofreads/{proofread_id} | Delete 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 list | GET /v3/video-translations/proofreads | List Proofread Sessions |
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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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> | Destination folder ID in the caller’s workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. |
--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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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> | Destination folder ID in the caller’s workspace, for example one returned by POST /v3/folders. Omit, pass null, or pass an empty string to place the result at the workspace root. The id must name a folder that is not in the trash and that the caller can write to; an unknown id, a folder in another workspace, a project of another kind such as a brand kit, or a trashed folder is rejected with 404 before anything is created. |
--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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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 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 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, <break time=“0.35s”/>); millisecond values are not supported. (required) |
--voice-id <value> | Voice ID from the voice catalog. The voice must be one the Starfish engine supports: a stock voice, a designed voice, or an instant clone. List them with GET /v3/voices?engine=starfish. A professional HeyGen Voice clone is synthesized by POST /v3/models/audio/tts instead. (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 |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
--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 rotate-secret
| Flag | Description |
|---|---|
--idempotency-key <value> | Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent. Example: 550e8400-e29b-41d4-a716-446655440000 |
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 |