HeyGen

Delete a Video via DELETE /v1/video.delete

delete an existing webhook endpoint via DELETE /v1/webhook/endpoint.delete

Deletes a Digital Twin by its ID. via DELETE /v2/video_avatar/{avatar_id}

Permanently delete a video. Supports both generated and translated videos. via DELETE /v2/videos/{video_id}

Soft-deletes an AI clip job and its clips. via DELETE /v3/ai-clipping/{job_id}

Permanently deletes an asset. The asset must belong to the caller's workspace and not already be deleted. via DELETE /v3/assets/{asset_id}

Permanently deletes an avatar group and all its associated looks. Cannot delete public or community groups. via DELETE /v3/avatars/{group_id}

Deletes an avatar look and its backing resource. Supported types: photo_avatar, digital_twin, and kit-based looks. Studio avatar (model_index) types cannot be deleted via the API. **Warning:** deleting the last look in a group also deletes the parent group. Subsequent requests referencing that group id (e.g. `POST /v3/avatars` with `avatar_group_id`) return 404 not found. via DELETE /v3/avatars/looks/{look_id}

Soft-deletes a background removal job. via DELETE /v3/background-removals/{job_id}

Deletes a brand glossary. This cannot be undone: there is no way to restore a deleted brand glossary through the API. The glossary stops being returned by this API at once, and stops applying: neither its pronunciation terms nor its translation rules affect anything generated afterwards. Videos already generated with the glossary are unaffected, since their audio was synthesized at the time. A video or translation still configured with a deleted glossary keeps working rather than failing. via DELETE /v3/brand-glossaries/{brand_glossary_id}

Deletes a brand kit, along with the colors, logos and fonts it holds. This cannot be undone: there is no way to restore a deleted brand kit through the API. A kit that is still assembling can be deleted at any time. Videos already generated with the kit are unaffected, since their brand colors were applied at render time. A video agent still configured with a deleted kit will report the id as invalid on its next use. A brand kit shared into your workspace by another workspace can be read but not deleted, and returns 403. via DELETE /v3/brand-kits/{brand_kit_id}

Soft-deletes a HyperFrames render. Subsequent GETs return 404. via DELETE /v3/hyperframes/renders/{render_id}

Permanently deletes a lipsync job and its associated files. This action cannot be undone. via DELETE /v3/lipsyncs/{lipsync_id}

Deletes the caller-owned model-backed audio voice. The voice is removed from subsequent reads, but a voice cannot be deleted while its status is `PENDING`. Wait for training to finish and retry. Repeating a successful deletion returns the same successful response. via DELETE /v3/models/audio/voices/{voice_id}

Soft-deletes a podcast so it no longer appears in the get/list endpoints. Does not cancel in-flight generation or permanently remove files. Idempotent: deleting an already-deleted podcast succeeds. via DELETE /v3/podcasts/{podcast_id}

Permanently deletes a video translation and its associated files. This action cannot be undone. via DELETE /v3/video-translations/{video_translation_id}

Permanently deletes a video and its associated files. This action cannot be undone. via DELETE /v3/videos/{video_id}

Deletes a voice clone owned by the caller. The voice must not be in use by any template. The voice is removed from your voice list and no longer counts against your voice clone limit. Deleting an already-deleted or unknown voice returns 404 `voice_not_found` (not 200) — a delete-then-list flow should treat that 404 as success, not an error. via DELETE /v3/voices/{voice_id}

Permanently removes a webhook endpoint. Events will no longer be delivered to this URL. This action cannot be undone. via DELETE /v3/webhooks/endpoints/{endpoint_id}

List voices available for TTS generation with cursor-based pagination. Filter by type (public/private), language, and gender. via GET /v1/audio/voices

This endpoint is used to retrieve a list of brand voices your created via GET /v1/brand_voice/list

Retrieves a list of folders with optional filters. via GET /v1/folders

Returns the authenticated user's profile, remaining credits or balance, and billing details. The billing_type field indicates which billing object is populated: wallet (prepaid balance), subscription (OAuth credit pools), or usage_based (metered spending). via GET /v1/user/me

This endpoint retrieves a list of videos associated with the user. via GET /v1/video.list

This endpoint allows you to retrieve the status and details of a specific video. via GET /v1/video_status.get

list all your registered webhook endpoints via GET /v1/webhook/endpoint.list

list all supported webhook events via GET /v1/webhook/webhook.list

List all available workflow types with their input/output schemas. via GET /v1/workflows

Poll the status and output of a workflow execution. **Single-workflow executions** return output in the `output` field. **Multi-workflow graph executions** return all outputs in the `outputs` field, keyed by workflow ID. via GET /v1/workflows/executions/{execution_id}

List all avatars in one avatar group via GET /v2/avatar_group/{group_id}/avatars

List all avatar groups via GET /v2/avatar_group.list

You can get your Avatars and Talking Photos(Photo Avatars) with this endpoint. via GET /v2/avatars

Get the details of a photo avatar via GET /v2/photo_avatar/{id}

Check photo/look generation status via GET /v2/photo_avatar/generation/{generation_id}

Get the training status of a avatar group via GET /v2/photo_avatar/train/status/{group_id}

This API now supports New AI Studio! via GET /v2/template/{template_id}

This API now supports New AI Studio! via GET /v2/templates

Get Remaining Quota via GET /v2/user/remaining_quota

Checks the current status of the Digital Twin generation process and returns relevant details. via GET /v2/video_avatar/{avatar_id}

Check Translation Status via GET /v2/video_translate/{video_translate_id}

Get the caption file (SRT or VTT format) for a completed video translation. The translation must have status "completed" — use get_video to check status first. Requires enable_caption=true when creating the translation. via GET /v2/video_translate/caption

List all supported target language codes for video translation. Call this before create_video_translate to validate language choices. via GET /v2/video_translate/target_languages

List videos in the account with pagination and optional filtering. via GET /v2/videos

Get detailed information about a video including status, URLs, and metadata. Supports both generated and translated videos. via GET /v2/videos/{video_id}

List All Voices (V2) via GET /v2/voices

Returns a cursor-paginated list of AI clip jobs in the authenticated user's workspace, newest first. via GET /v3/ai-clipping

Returns the full job resource including produced clips, statuses, and presigned download URLs. via GET /v3/ai-clipping/{job_id}

**Beta** — this endpoint may change with a few days' notice. Lists a workspace member's uploaded assets, newest first, with cursor-based pagination. Returns the same asset objects as GET /v3/assets/{asset_id}. The 'username' parameter (the 'owner' value on asset items) is required while the endpoint is in beta and will become an optional filter in a future release. Results are that member's non-deleted assets, across all folders, that the caller has access to — each item carries 'owner' and 'folder_id'. Pass the optional folder_id to narrow to one folder (empty folder_id = root-level assets); omit it for everything. via GET /v3/assets

Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API); for asset batches it holds the asset_id. via GET /v3/assets/batches/{batch_id}

Returns metadata for an asset in the caller's workspace — including owner, upload timestamp, file type, and a publicly accessible URL. via GET /v3/assets/{asset_id}

Semantically search re-hosted public images and icons by natural-language description, e.g. 'pepperoni pizza on a wooden table' or 'minimalist rocket icon'. Returns assets ranked by similarity, each with a stable public URL, plus cursor-based pagination. via GET /v3/assets/search

Returns statuses for up to 100 assets in one request, addressed by comma-separated asset_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API). via GET /v3/assets/statuses

Semantically search the audio catalog by natural-language description — set type=music (the default) for background music (e.g. 'upbeat lofi hip-hop', 'tense cinematic riser') or type=sound_effects for SFX (e.g. 'whoosh for a scene change', 'cash register cha-ching'). Returns tracks ranked by similarity, each with a pre-signed download URL, plus cursor-based pagination. via GET /v3/audio/sounds

Get the status of a streaming avatar session. `status` is one of `pending` (workflow starting), `streaming` (the `hls_url` is live), `completed` (finished — `end_reason` describes how), or `error` (`error_message` describes the failure). Poll this after POST /v3/avatar-realtime until `hls_url` is present. via GET /v3/avatar-realtime/{stream_id}

Returns a paginated list of avatar groups (characters). Each group contains one or more looks. Filterable by ownership. via GET /v3/avatars

Returns details for a specific avatar group including name, gender, preview URLs, looks count, and training status. via GET /v3/avatars/{group_id}

Returns a paginated list of avatar looks (outfits, poses, styles). Filterable by group_id, avatar_type, and ownership. The look id is the avatar_id to pass when creating a video. via GET /v3/avatars/looks

Returns details for a specific avatar look including supported engines, preferred orientation, preview URLs, and training status. via GET /v3/avatars/looks/{look_id}

Returns a paginated list of background removal jobs for the account, newest first. via GET /v3/background-removals

Returns a background removal job including its status and, once completed, presigned download URLs for the produced layers. via GET /v3/background-removals/{job_id}

List brand glossaries (custom term mappings, a.k.a. brand voices) in the authenticated user's workspace. A brand glossary controls how custom terms are pronounced in generated speech — for example, speaking "HeyGen" as "hey-jen" — and how they are handled when a video is translated: Don't Translate terms kept as-is, and Force Translate terms with a fixed replacement. Pass the returned `brand_glossary_id` when creating a video or translation to apply the glossary. Use GET /v3/brand-glossaries/{brand_glossary_id} to see which terms it remaps, POST /v3/brand-glossaries to create one, and PATCH /v3/brand-glossaries/{brand_glossary_id} to change one. via GET /v3/brand-glossaries

Returns one brand glossary with its full term list, so you can see exactly which terms are remapped and how. Use this to verify a glossary's contents when a generated video pronounces or translates a term unexpectedly. Pronunciations affect generated audio only: a term keeps its original spelling in captions and subtitles while being spoken as its `pronunciation`. Translation rules apply only when the glossary is used by a translation feature — video translation, Studio script translation, and on-screen text translation: `do_not_translate_terms` are kept untranslated in every target language, and `forced_translations` replace their `term` with their `translation` in every target language. They have no effect on video generation or text-to-speech requests; only `terms` applies there. Either list is omitted from the response when the glossary has no rules of that kind. Tone settings are managed in the HeyGen web app under Brand Kit and are not returned here; editing a glossary through this API leaves them unchanged. via GET /v3/brand-glossaries/{brand_glossary_id}

Returns brand kits available in the authenticated user's workspace. Each brand kit contains colors, fonts, and logos that can be applied to Video Agent sessions. Use the returned brand_kit_id with POST /v3/video-agents to generate on-brand videos. via GET /v3/brand-kits

Returns one brand kit with the colors, logos and fonts it was built from, and which of them play which role. A brand kit imported from a website is assembled in the background: while status is 'loading' the collections and roles are provisional, and they are final once status is 'completed'. Poll every 2 to 5 seconds while status is 'loading'; a website import usually settles in under two minutes, and fonts are typically the last thing to land. via GET /v3/brand-kits/{brand_kit_id}

Returns the job resource: lifecycle status, progress, and — once completed — the presigned download URL of the cleaned video plus removal statistics (num_cuts, reduction_pct, durations). via GET /v3/filler-word-removals/{filler_word_removal_id}

Returns a cursor-paginated list of HyperFrames renders in the account, newest first. via GET /v3/hyperframes/renders

Returns full details for a single HyperFrames render, including status and signed video_url when complete. via GET /v3/hyperframes/renders/{render_id}

Returns a paginated list of all lipsync jobs in the account. via GET /v3/lipsyncs

Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API). via GET /v3/lipsyncs/batches/{batch_id}

Returns details for a lipsync job including status, video_url, caption_url, and failure info if applicable. via GET /v3/lipsyncs/{lipsync_id}

Returns statuses for up to 100 lipsyncs in one request, addressed by comma-separated lipsync_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API). via GET /v3/lipsyncs/statuses

Returns the model-backed audio voices in the caller's workspace, ordered newest first. Use `limit` and `token` to retrieve additional pages. via GET /v3/models/audio/voices

Returns one caller-owned model-backed audio voice and its current lifecycle state. `PENDING` covers queued and running work, `ACTIVE` is ready for inference, and `FAILED` is terminal. via GET /v3/models/audio/voices/{voice_id}

Returns a paginated list of the podcasts in the authenticated workspace, newest first. via GET /v3/podcasts

Returns a podcast's status and, once completed, its video_url, thumbnail_url, and duration. via GET /v3/podcasts/{podcast_id}

Retrieves template details by ID, including variables available for replacement and scene mappings for the New AI Studio. via GET /v3/template/{template_id}

Returns a paginated list of API-ready templates in the workspace. Templates are created and edited in the HeyGen web editor; only templates with variables defined are listed. via GET /v3/templates

Returns template details including its variable schema (with current default values) and scenes. Variable defaults are returned in the same shape the generate request accepts, so a response can be edited and posted back. Only draft version 4 templates (the current editor format) are supported. via GET /v3/templates/{template_id}

Returns the authenticated user's profile, remaining credits or balance, and billing details. via GET /v3/users/me

Returns a paginated list of video agent sessions for the authenticated user, sorted newest-first. via GET /v3/video-agents

Returns the current status, progress, video_id, and recent chat messages for a session. via GET /v3/video-agents/{session_id}

Returns a single session resource (image, video, draft, avatar, voice, etc.) by its resource_id. via GET /v3/video-agents/{session_id}/resources/{resource_id}

Returns all videos produced within a Video Agent session, sorted newest-first. via GET /v3/video-agents/{session_id}/videos

Returns curated visual style templates available for Video Agent sessions. Each style controls scene composition, pacing, and aesthetics. Supports tag filtering (e.g. 'cinematic', 'retro-tech'). via GET /v3/video-agents/styles

Return aggregate batch status and one cursor-paginated page of comparison items. via GET /v3/video-quality/comparisons/batches/{batch_id}

Return the latest state and result or terminal error for one comparison. via GET /v3/video-quality/comparisons/{comparison_id}

Returns a paginated list of all video translation jobs in the account. via GET /v3/video-translations

Returns batch aggregate status and one page of items with their ids and statuses. Item statuses are one of queued, processing, completed, or failed. The per-item id is returned as video_id (the batch read model is shared with the videos batch API). via GET /v3/video-translations/batches/{batch_id}

Returns details for a translation job including status, output language, video_url, and failure info if applicable. via GET /v3/video-translations/{video_translation_id}

Returns all supported target language names for video translation. via GET /v3/video-translations/languages

Returns the status and details of a proofread session. via GET /v3/video-translations/proofreads/{proofread_id}

Returns presigned download URLs for the edited and original SRT files of a completed proofread session. via GET /v3/video-translations/proofreads/{proofread_id}/srt

Returns statuses for up to 100 video translations in one request, addressed by comma-separated video_translation_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. Each returned entry carries its id as video_id (the status read model is shared with the videos batch API). via GET /v3/video-translations/statuses

Returns a paginated list of all videos in the account. Filterable by folder_id or title substring. via GET /v3/videos

Returns batch aggregate status and one page of items with their video ids and statuses. Item statuses are one of queued, processing, completed, or failed. via GET /v3/videos/batches/{batch_id}

Returns details for a video including status, video_url, thumbnail_url, duration, and failure info if applicable. via GET /v3/videos/{video_id}

Returns the video's scenes together with the video-level context needed to use them. Describes the video as it stands now, including any edits made in the editor after it was created. The scene list is never paginated. Each scene splits by the role a thing plays: `background` fills the frame, `elements` are placed within it, and `script` is the audio delivered over it. A whole-frame image or clip lands in `background`, so code that reads only `elements` misses it. Element types are an open set: treat an unrecognized type as an element to skip rather than an error, and expect a type value to become more specific over time. Every element a scene places appears in `elements`, so the count is always truthful, but only `avatar`, `image` and `video` are described in full; `group` and `mask` carry their children; the rest carry an `id` and a `type` and nothing more. **What this does not describe.** A video may contain more than this response expresses, and a video rebuilt from it will differ in these respects: element geometry (position, size, opacity); the text inside a text element; scene and element animations and scene effects; per-scene caption styling, where only whether captions are enabled is reported; background audio, which is video-level and belongs to no scene, so a rebuild loses the music; and some per-avatar values, which this version does not return. via GET /v3/videos/{video_id}/scenes

Returns statuses for up to 100 videos in one request, addressed by comma-separated video_ids and/or batch_ids query params. Statuses are one of queued, processing, completed, or failed, plus not_found for unknown or unowned ids. via GET /v3/videos/statuses

Returns a paginated list of voices, filterable by type, engine, language, and gender. Use engine=starfish for voices compatible with the TTS endpoint. via GET /v3/voices

Returns details for a specific voice, including clone workflow status when available. Use this to poll a voice clone until its status is 'complete'. via GET /v3/voices/{voice_id}

Returns a paginated list of registered webhook endpoints. via GET /v3/webhooks/endpoints

Returns all available webhook event types with human-readable descriptions. via GET /v3/webhooks/event-types

Returns a paginated history of delivered webhook events. Filterable by event_type or entity_id. via GET /v3/webhooks/events

Returns a paginated list of runs for the workflow named by the required `workflow_id` query parameter, newest first. List items are compact status rows; fetch a single run for its outputs and error detail. via GET /v3/workflow-runs

Returns a single workflow run: the exact version it is pinned to, created/started/completed timestamps, aggregate node progress, a sanitized terminal error (if any), and every declared output. A terminal run's response is self-contained — media outputs carry a fresh read-time URL (with expiry unless the object is public), and inline JSON outputs carry their value directly, bounded at 64 KiB per output and 256 KiB per response (larger values are delivered as references whose URL serves the value as a JSON document). The response body size does not grow with the run's node count; per-node detail lives under /nodes. via GET /v3/workflow-runs/{run_id}

Paginated per-node diagnostics for one run: node id, status, timestamps, and a sanitized error for failed nodes. Diagnostics only — a run's declared outputs live on the run resource itself. via GET /v3/workflow-runs/{run_id}/nodes

Returns a paginated list of workflow definitions. via GET /v3/workflows

Returns a single workflow definition, including its current mutable draft graph. via GET /v3/workflows/{workflow_id}

Returns a paginated list of immutable, compiled versions for a workflow definition. via GET /v3/workflows/{workflow_id}/versions

Returns a single immutable, compiled workflow version, including its full plan summary. via GET /v3/workflows/{workflow_id}/versions/{version_number}

Discovery catalog of authorable node types, grouped by family with per-variant config schema and ports. Discovery metadata only: publishing a workflow version remains the authoritative validation of a graph. via GET /v3/workflows/node-types

update an existing webhook endpoint via PATCH /v1/webhook/endpoint.update

Updates an avatar group. Currently supports setting `default_voice_id`: the voice becomes the avatar's default for video generation and is linked to the group if it was not already. Accepts any voice available to your workspace, including imported voice clones. Only supported for avatars you own — public avatars cannot be updated. via PATCH /v3/avatars/{group_id}

Updates the display name of an avatar look. Only supported for photo avatar and digital twin look types. via PATCH /v3/avatars/looks/{look_id}

Updates a brand glossary. Each field is replaced independently: a field you omit is left untouched, a field you send replaces that value in full, and an empty array removes every entry from that list. There is no way to add a single entry — read the glossary, append to the list, and send the whole list back. Renaming to a name another glossary in your workspace already uses returns 409. A glossary's tone settings are managed in the HeyGen web app and are never modified by this endpoint, so a glossary edited there keeps them through an update made here. via PATCH /v3/brand-glossaries/{brand_glossary_id}

Updates a brand kit's name or its role assignments — which color plays which part, which logo is the main one, and which font is used for headings and body text. A field you omit is left unchanged. Creation assigns these roles automatically, with no human in the loop, so this is how a caller corrects them. Each role object is replaced in full rather than merged: send the roles you want to keep, since a role you leave out of the object is cleared. Send an empty object to clear a role entirely. A cleared role stays cleared and is not recomputed later. Sending null for any field is rejected: omit it to leave it unchanged. Role edits require an assembled kit and return 409 while status is 'loading' or 'error'. Renaming is allowed at any time. Editing the colors themselves is not supported here yet. A brand kit shared into your workspace by another workspace is readable but not editable, and returns 403. via PATCH /v3/brand-kits/{brand_kit_id}

Updates the display title of a lipsync job. via PATCH /v3/lipsyncs/{lipsync_id}

Updates the display title of a video translation job. via PATCH /v3/video-translations/{video_translation_id}

Updates the URL and/or subscribed event types for a webhook endpoint. The events array is fully replaced — include all types you want to keep. via PATCH /v3/webhooks/endpoints/{endpoint_id}

Replaces the mutable draft product graph. Rejected (409) if `expected_revision` is stale, and 422 `graph_invalid` if the graph uses node types not available for authoring — the draft is left unchanged in both cases. via PATCH /v3/workflows/{workflow_id}

Synthesize speech audio from text using a specified voice. Returns a URL to the generated audio file along with duration and optional word-level timestamps. via POST /v1/audio/text_to_speech

Updates an existing brand voice with specified changes. Only the fields that need to be modified should be included in the request body. via POST /v1/brand_voice/{brand_voice_id}

Updates the name of an existing folder. via POST /v1/folders/{folder_id}

Restore Folder via POST /v1/folders/{folder_id}/restore

Moves a folder to the trash. via POST /v1/folders/{folder_id}/trash

Create Folder via POST /v1/folders/create

Create a video from a text prompt using HeyGen's Video Agent. This is the recommended way to create videos — just describe what you want and the agent handles avatar selection, scripting, and production. The video is generated asynchronously — use the returned video_id to poll status via GET /v2/videos/{video_id}. via POST /v1/video_agent/generate

Generates a webm video with transparent background and an avatar speaking the input text. You can customize the avatar's pose, style, and voice, as well as the dimensions of the video. via POST /v1/video.webm

Add a Webhook Endpoint via POST /v1/webhook/endpoint.add

Submit a single workflow for asynchronous execution. Returns an execution_id that can be polled via GET /v1/workflows/executions/{execution_id}. via POST /v1/workflows/executions

Submit a multi-workflow graph for asynchronous execution. Returns an execution_id that can be polled via GET /v1/workflows/executions/{execution_id}. via POST /v1/workflows/graph-executions

Add motion to an existing photo avatar, returns the id of the new avatar that has motion via POST /v2/photo_avatar/add_motion

This api adds sound effect into a photo avatar via POST /v2/photo_avatar/add_sound_effect

Add other looks to existing photo avatar group via POST /v2/photo_avatar/avatar_group/add

This api can be used to create a photo avatar group For generated photo avatar, pass the generation_id and the image_key For user uploaded avatar, first upload the photo using the upload assets api. Then use the key as image_key This api only allows using one photo to establish the identity, you can add more photos using the add looks api via POST /v2/photo_avatar/avatar_group/create

This endpoint can be used to generate additional looks for a trained photo avatar group. The photo avatar group must be trained to use this endpoint. via POST /v2/photo_avatar/look/generate

This endpoint will generate photos that can be used to create photo avatars, returns a generation id, which can be used in the check generation status endpoint to get status and final image/image keys via POST /v2/photo_avatar/photo/generate

Train a photo avatar group. via POST /v2/photo_avatar/train

Call this api to upscale an avatar, can only be called on an avatar that has motion, returns the photo avatar id that is upscaled via POST /v2/photo_avatar/upscale

This API now supports New AI Studio! via POST /v2/template/{template_id}/generate

Submits the URLs for the required training footage and consent statement to create a Digital Twin. via POST /v2/video_avatar

This API now generates videos with our New AI Studio backend. via POST /v2/video/generate

Translate a video into one or more target languages. The translation runs asynchronously — the response contains a video_translate_id which can be used with get_video to poll status and retrieve the download URL when complete. Use list_video_translate_languages to discover supported language codes before calling this endpoint. Key parameters: - video_url (required): URL of the source video to translate. - output_language: Single target language code. Mutually exclusive with output_languages. - output_languages: Array of target language codes for batch translation. Mutually exclusive with output_language. - mode: "speed" (default, faster) or "precision" (higher quality, uses avatar inference). - brand_glossary_id (preferred) / brand_voice_id (legacy alias): Brand glossary ID for custom term translations (e.g. translate 'Reformer' as Pilates equipment, not as a political activist). Discover IDs via GET /v3/brand-glossaries. - stock_voice_config: Use a preset stock voice instead of recreating the original speaker's voice (set use_stock_voice=true). Enterprise feature, available for selected accounts and languages by request. - srt_url / srt_role: Custom subtitle file. - fps_mode: Frame rate mode ("vfr", "cfr", "passthrough"). Only valid when audio_url is provided. via POST /v2/video_translate

Create a video from a specific avatar or image with full control over avatar, voice, and script. Use this only when you need explicit control over avatar selection and scripting. For most video creation, use the create_video_agent tool instead which handles these choices automatically. Supports photo avatars, video avatars (digital twins), and direct image input. The video is generated asynchronously — poll status via GET /v2/videos/{video_id}. via POST /v2/videos

Submit a source video and return a job id immediately. The job runs asynchronously and produces one or more short clips per the requested output_settings. Poll GET /v3/ai-clipping/{id} or subscribe to ai_clipping.success / ai_clipping.fail webhooks. via POST /v3/ai-clipping

Finalize a direct-to-S3 upload into a reusable asset. Call after the upload PUT returns 200. Idempotent: repeated calls return the same finalized asset. via POST /v3/assets/{asset_id}/complete

Finalize every uploaded file in a batch. Call after all upload PUTs return 200. Each file is validated and ingested asynchronously and independently, so one bad file does not fail the rest. Returns 202 with the batch_id; poll GET /v3/assets/batches/{batch_id} for per-item progress. Idempotent: a repeated call re-drives the same batch. via POST /v3/assets/complete/batches

Begin a direct-to-S3 upload. Returns an asset_id and a presigned upload_url; PUT the file bytes to upload_url, then call POST /v3/assets/{asset_id}/complete. Unlike POST /v3/assets (which proxies the bytes), this never sends the file through the API. via POST /v3/assets/direct-uploads

Request up to 100 presigned direct-to-S3 upload URLs in a single call. Returns a batch_id and one upload slot per file (asset_id + presigned upload_url + required headers). PUT each file's bytes to its upload_url, then call POST /v3/assets/complete/batches to finalize the whole batch. This is synchronous — no bytes flow through the API. Pass an Idempotency-Key header to make retries safe (the same key returns the same batch). via POST /v3/assets/direct-uploads/batches

Start a low-latency streaming avatar session and return a `stream_id`. Three modes, selected by the `type` discriminator: `tts` (speak a fixed script), `audio` (drive lip-sync from a pre-existing audio asset), and `text_stream` (seed with initial text, then append more text deltas over time via POST /v3/avatar-realtime/{stream_id}/text — e.g. as an upstream LLM streams tokens). Poll GET /v3/avatar-realtime/{stream_id} for the session status and HLS playback URL. via POST /v3/avatar-realtime

Cancel a running streaming session. Idempotent: `cancelled` is true when this request initiated the cancellation, or false when the session was already terminal (completed, failed, or previously cancelled). via POST /v3/avatar-realtime/{stream_id}/cancel

Append a text delta to a session created with `type: text_stream`. Send fragments as they become available (e.g. tokens streamed from an upstream LLM); the avatar speaks them in order. Set `final: true` on the last delta to close input — further appends to a closed stream return 410. Returns the total bytes buffered so far. via POST /v3/avatar-realtime/{stream_id}/text

Creates a new avatar from an image, video footage, or a text prompt. Supports photo, digital_twin, and prompt types. Avatar training is asynchronous. via POST /v3/avatars

Initiates the consent flow for an avatar group and returns a URL for the user to complete approval in their browser. Required before a private avatar can be used for video generation. The consent URL expires 24 hours after creation and is valid for one successful consent submission. A recording submitted after expiry fails and the group stays in pending consent status, so create a new consent link if the subject has not recorded within 24 hours. via POST /v3/avatars/{group_id}/consent

Submit a video to remove its background. Returns the created job; runs asynchronously, so poll Get Background Removal with the returned id. Once completed, the job carries presigned download URLs for the requested layers: 'foreground' (subject on a transparent background), 'mask' (grayscale alpha matte), and 'background' (the scene with the subject removed). Idempotency is opt-in via the request body's `request_id` field: re-sending the same `request_id` returns the *original* job (same `id`, same charge) without creating a new one. The HTTP `Idempotency-Key` header is *not* honored — see `request_id` for the supported contract. via POST /v3/background-removals

Creates a brand glossary in your workspace. Pass the returned `brand_glossary_id` when creating a video or translation to apply it. `name` must be unique within your workspace, compared without regard to case; a duplicate returns 409. `terms`, `do_not_translate_terms` and `forced_translations` may each be omitted to create an empty glossary you fill in later with PATCH /v3/brand-glossaries/{brand_glossary_id}. Pronunciations affect generated audio only — a term keeps its original spelling in captions and subtitles. `do_not_translate_terms` and `forced_translations` apply only when the glossary is used by a translation feature (video translation, Studio script translation, on-screen text translation), in every target language; they have no effect on video generation or text-to-speech requests. Tone settings are managed in the HeyGen web app and cannot be set here. via POST /v3/brand-glossaries

Creates a brand kit by importing brand assets from a public website, including logos, colors and font files found on the site. By calling this endpoint you confirm you have the rights and licenses necessary to upload, store and use those assets in HeyGen. The kit is assembled in the background: the returned brand_kit_id is usable immediately, but poll GET /v3/brand-kits/{brand_kit_id} every 2 to 5 seconds until its status is 'completed' before relying on its colors, logos or fonts. A website import usually settles in under two minutes. Send an Idempotency-Key header to make retries safe: without one, a retried request starts a second import of the same site. via POST /v3/brand-kits

Submit a video and return a job id immediately. The job runs asynchronously: it transcribes the audio, detects filler words ('um', 'uh', ...), removes them along with overlong silences, and renders one cleaned video — no review step. If the run changes nothing at all, the job completes with the original video as output and the charge is automatically refunded. Pricing: $0.30 per source minute, 1-minute minimum. Poll GET /v3/filler-word-removals/{id} or subscribe to filler_word_removal.success / filler_word_removal.fail webhooks. via POST /v3/filler-word-removals

Renders a HyperFrames composition (an HTML+JS+assets project bundled as a .zip) into a video. Submit the project via `url`, `asset_id` (pre-uploaded via POST /v3/assets), or inline `base64`. Returns a `render_id` to poll via GET /v3/hyperframes/renders/{render_id}. via POST /v3/hyperframes/renders

Replaces the audio on an existing video and re-animates the speaker's lip movements to match the new audio. Use mode: 'speed' for fast output or 'precision' for high-quality lip-sync. via POST /v3/lipsyncs

Submit up to 100 lipsync payloads as a single batch. Each payload becomes one batch item, created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/lipsyncs/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch. via POST /v3/lipsyncs/batches

Generates speech using the voice identified by `voice_id` and returns a URL for one completed mono PCM16 WAV file at 44.1 kHz. The request remains open until synthesis and output assembly finish. The voice must be an ACTIVE professional voice. Rate limit: 30 requests per minute per workspace member. via POST /v3/models/audio/tts

Creates a model-backed audio voice from one or more recordings, or retrains an existing professional voice when `voice_id` is supplied. Retraining requires only `voice_id` and source audio and retains the existing voice's ID, name, language, and mode. The voice is `PENDING` and unavailable for inference while either operation runs. Poll `GET /v3/models/audio/voices/{voice_id}` until its status becomes `ACTIVE` or `FAILED`. `Idempotency-Key` is optional; omitting it means repeated creation requests create separate voices. New voices require an unoccupied professional-voice slot. Each purchased slot provides five pooled trainings per monthly billing period, including initial training; failed trainings do not consume the allowance. via POST /v3/models/audio/voices

Generate a multi-avatar conversational podcast video from a topic and/or source files plus two avatars. Generation is asynchronous — use the returned podcast_id to poll status via GET /v3/podcasts/{podcast_id}. via POST /v3/podcasts

Generates a video from the template by replacing its variables (text, image, video, audio, character, voice). Use scene_ids to select, reorder, or repeat scenes — scenes must already exist in the template; the API cannot create new ones. Returns the created video object; poll GET /v3/videos/{video_id} or use webhooks for completion. Idempotent replays return the original creation-time snapshot (status and URLs as of the first request), not the video's current state. via POST /v3/templates/{template_id}

One-shot video generation from a prompt — agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes. via POST /v3/video-agents

Sends a follow-up message to an existing session. Use to answer agent questions, add context, or request edits to a generated video. Only valid for sessions created in chat mode. via POST /v3/video-agents/{session_id}

Halts an active agent run at its next checkpoint. Partial results are preserved. via POST /v3/video-agents/{session_id}/stop

Submit one pairwise video comparison. The server waits for a bounded synchronous result: completed comparisons return 200, while comparisons that continue asynchronously return 202 and can be polled by comparison_id. via POST /v3/video-quality/comparisons

Submit up to 100 pairwise video comparisons for asynchronous processing. via POST /v3/video-quality/comparisons/batches

Translates a video into one or more target languages with voice cloning and lip-sync. Returns one video_translation_id per language. Use mode: 'speed' (default) for fast turnaround or 'precision' for higher lip-sync quality. via POST /v3/video-translations

Submit up to 100 video-translation payloads (identical in shape to POST /v3/video-translations) as a single batch. A payload targeting multiple output_languages expands to one batch item per language, and each item is created and processed independently so one bad source does not fail the rest. Returns 202 with a batch_id; poll GET /v3/video-translations/batches/{batch_id} for progress. Pass an Idempotency-Key header to make retries safe — the same key returns the same batch. via POST /v3/video-translations/batches

Creates a proofread session that extracts editable subtitles from a video before final rendering. via POST /v3/video-translations/proofreads

Starts final video generation using the approved subtitles from a proofread session. via POST /v3/video-translations/proofreads/{proofread_id}/generate

Creates a video from a HeyGen avatar or an arbitrary image. Supports scripts or pre-recorded audio for lip-sync. Supports the Avatar III, Avatar IV, and Avatar V engines; set the 'engine' field to select. Avatar IV is used by default when 'engine' is omitted. via POST /v3/videos

Submit up to 100 video creation payloads in one request and return a batch id immediately. Videos are created asynchronously; poll GET /v3/videos/batches/{batch_id} for per-item video ids and statuses. via POST /v3/videos/batches

Returns up to 3 voices matching a natural language description (e.g. 'warm, confident female narrator'). Use the seed parameter to get different batches of results. via POST /v3/voices

Creates a voice clone from an audio file. Returns a voice_clone_id that can be polled via GET /v3/voices/{voice_clone_id} until the status is 'complete'. The resulting voice can be used with POST /v3/voices/speech and POST /v3/videos. via POST /v3/voices/clone

Synthesize speech audio from text using a specified voice. The voice must support the starfish engine — use GET /v3/voices?engine=starfish to find compatible voices. Supports plain text and SSML. Speed range: 0.5–2.0x. Returns a URL to the generated audio file along with duration and optional word-level timestamps. via POST /v3/voices/speech

Registers an HTTPS URL to receive webhook event notifications. Returns the endpoint details and a signing secret. The signing secret is only shown at creation and rotation — store it securely. via POST /v3/webhooks/endpoints

Generates a new signing secret for a webhook endpoint and immediately invalidates the old one. Store the new secret securely — it will not be shown again. via POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret

Starts a run of the workflow named in the request body. Omit `version_number` to run the latest published version: it is resolved exactly once, when the request's `Idempotency-Key` is first accepted, and the response reports the exact `version_number` (and `version_id`) the run is pinned to. Repeating the request with the same key always returns that original run — including after a newer version is published — while reusing the key with a different workflow, version, or inputs is rejected with a 409 `conflict` and starts nothing. Validates inputs against the resolved version's frozen plan, creates the run and its pending node runs in a single transaction, and then submits the run for execution. A 201 or 200 means the run has been accepted for execution; if the submission cannot be confirmed the response is a retryable 503 (see below) and the run is left pending. `Idempotency-Key` is REQUIRED on this endpoint, because repeating the request with the same key is how a 503 is recovered. No video is created and nothing is charged by this call. Media inputs accept an asset id (as a bare string or `{"type": "asset_id"}` object), a publicly accessible HTTPS source URL (`{"type": "url"}`), or inline base64 content (`{"type": "base64"}`). URL and inline sources are imported into your asset library before the run executes, so the run is immune to the source changing or expiring afterwards; retries with the same `Idempotency-Key` reuse the already-imported asset. URL sources are fetched with a 16 MB limit for images and 32 MB for audio; inline content is limited to 5 MB for images and 16 MB for audio and must also fit this endpoint's 1 MiB request-body limit — for anything larger, upload via POST /v3/assets/direct-uploads and pass the asset_id. via POST /v3/workflow-runs

Requests cancellation of a run. Idempotent and defined for every run state: a 200 reflects a settled outcome (the run is terminal now — canceled by this request, or already finished, in which case its terminal status is unchanged and reported as-is). When cancellation cannot be confirmed the response is a retryable 503 and the run is unchanged. A terminal run can never move backward. via POST /v3/workflow-runs/{run_id}/cancel

Atomically creates a workflow and publishes its required product graph as immutable version 1: the graph is validated and compiled first, then the workflow, its published version 1, and its `active` status commit together. The response's `latest_version` names the exact version this request published, ready to run. A graph that fails validation (including node types not available for authoring — see the node-types catalog) returns 422 `graph_invalid` and creates nothing; a name already used in the space returns 409 `conflict` with no partial writes. Idempotency (authoring contract): send an `Idempotency-Key` and a retry of the SAME request replays the original response body with **HTTP 200** (only the body is cached, not the original 201; the workflow already exists on a replay). Reusing a key with a different name, graph, or metadata returns 409 `conflict` instead of replaying. Keys are held in Redis for 24 hours; if the cache is unavailable the request executes and a duplicate retry converges on the duplicate-name 409. This differs from run creation's idempotency, which is durable (DB-backed, no expiry). A replay is a snapshot of the original response — later changes (e.g. archival) do not appear in it. via POST /v3/workflows

Compile the complete product graph in the request body and persist it as the next immutable version. The workflow's internal draft is neither read nor modified. Returns 201 when a new version is created and 200 when the latest version is already identical (republishing the same graph is a no-op that returns it). Republishing an older graph after a newer one creates a NEW version — version history is append-only, so rollback means republishing the prior graph. Idempotency (authoring contract): send an `Idempotency-Key` and a retry of the SAME request replays the original response body with **HTTP 200 even if the original call returned 201** — only the body is cached, not its status. Do not key 'just created' behaviour off the status code alone on a replay; compare `version_number` against what you already hold. Reusing a key with a different graph — or against a different `workflow_id` — returns 409 `conflict` instead of replaying. Keys are held in Redis for 24 hours; if the cache is unavailable the request executes and an identical retry converges on the 200-existing-version answer — provided no different publish landed in between; otherwise the retry creates a new version, since history is append-only. This differs from run creation's idempotency, which is durable (DB-backed, no expiry). A replay is a snapshot of the original response. A graph that fails validation returns 422 `graph_invalid` with every issue listed in `error.errors[]`, and nothing is published — the latest version is unchanged. via POST /v3/workflows/{workflow_id}/versions

Replaces the proofread subtitles with an edited SRT file. via PUT /v3/video-translations/proofreads/{proofread_id}/srt