HeyGen Avatar Video

Returns a paginated list of video agent sessions for the authenticated user, sorted newest-first.

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.

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').

Returns the current status, progress, video_id, and recent chat messages for a session.

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.

Returns a single session resource (image, video, draft, avatar, voice, etc.) by its resource_id.

Halts an active agent run at its next checkpoint. Partial results are preserved.

Returns all videos produced within a Video Agent session, sorted newest-first.

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

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.

Returns details for a video including status, video_url, thumbnail_url, duration, and failure info if applicable.

Permanently deletes a video and its associated files. This action cannot be undone.

Returns a video's scenes as it stands now, with the edit_version to send when editing. Each scene has a background, placed elements and a script. Skip element types you do not recognize. Geometry, text content, animations and background music are not described. A video whose editor document is still being prepared returns 409 resource_not_ready; retry after it advances.

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.

Creates a private template from one of your videos, copying its scenes, avatars, script and media. URL-to-Video and older editor videos return template_source_unsupported. The template starts with no variables; declare them with PUT /v3/templates/{template_id}/variables.

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.

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.

Renames a template. Other properties are edited in the HeyGen editor or through PUT /v3/templates/{template_id}/variables. Returns the template detail.

Soft-deletes a template. It disappears from the list and can no longer be used to generate videos; videos already generated from it are unaffected. Templates managed by another HeyGen product cannot be deleted here.

Replaces a template's full set of variables: any variable you omit is removed. Media, character and voice variables bind to a node by element_id, listed under composition in GET /v3/templates/{template_id}. A text variable with match turns that text into a {{name}} placeholder.

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

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.

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.

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.

Returns details for a specific voice, including clone workflow status when available. Use this to poll a voice clone until its status is 'complete'.

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.

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.

Returns a paginated list of all video translation jobs in the account.

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.

Returns all supported target language names for video translation.

Returns details for a translation job including status, output language, video_url, and failure info if applicable.

Updates the display title of a video translation job.

Permanently deletes a video translation and its associated files. This action cannot be undone.

Returns a cursor-paginated list of AI clip jobs in the authenticated user's workspace, newest first.

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.

Returns the full job resource including produced clips, statuses, and presigned download URLs.

Soft-deletes an AI clip job and its clips.

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.

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.

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.

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.

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).

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).

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.

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).

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).

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.

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.

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).

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).

Returns the authenticated user's profile, remaining credits or balance, and billing details.

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

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

Lists the look templates and Look Packs your workspace can apply with POST /v3/avatars/looks. Send an item's id as template_id and its type as type. Filter by gender to match your avatar.

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.

Generates new looks for an existing avatar from reference_look_id. type: look_pack applies a Look Pack; type: template applies one look template and produces two looks. Billing happens when the request is accepted: an API key is charged 1 API credit per look, and a connected integration (OAuth, including MCP) the method's standard price from workspace credits. Free-tier MCP access cannot use this endpoint. Poll GET /v3/avatars/looks/{id} until each look finishes.

Returns details for a specific avatar look including supported engines, preferred orientation, preview URLs, and training status.

Updates the display name of an avatar look. Only supported for photo avatar and digital twin look types.

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.

Returns details for a specific avatar group including name, gender, preview URLs, looks count, and training status.

Updates an avatar group you own. Currently sets default_voice_id, the voice this avatar uses by default; any voice in your workspace works, including clones. Public avatars cannot be updated.

Permanently deletes an avatar group and all its associated looks. Cannot delete public or community groups.

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.

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.

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.

Returns metadata for an asset in the caller's workspace — including owner, upload timestamp, file type, and a publicly accessible URL.

Permanently deletes an asset. The asset must belong to the caller's workspace and not already be deleted.

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.

Creates a folder at the root or inside parent_id. Pass its folder_id to POST /v3/videos or POST /v3/video-translations to file output there. Names need not be unique, so store the ids you receive. Send an Idempotency-Key to make retries safe.

Returns one folder in your workspace, including one in the trash (is_trash). Use it to check that a stored folder_id still exists. Deleted folders and folders in other workspaces return 404.

Returns a paginated list of all lipsync jobs in the account.

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.

Returns details for a lipsync job including status, video_url, caption_url, and failure info if applicable.

Updates the display title of a lipsync job.

Permanently deletes a lipsync job and its associated files. This action cannot be undone.

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". 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.

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 may 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. Translation rules are managed in the HeyGen web app and cannot be set here.

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 a term unexpectedly. Pronunciations affect generated audio only: a term keeps its original spelling in captions and subtitles while being spoken as its pronunciation. A glossary can also carry translation rules, which control how terms are handled when a video is translated. Those are managed in the HeyGen web app under Brand Kit and are not returned here; editing a glossary through this API leaves them unchanged.

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 terms array removes every term. There is no way to add a single term — read the glossary, append to terms, and send the whole list back. Renaming to a name another glossary in your workspace already uses returns 409. A glossary's translation rules 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.

Deletes a brand glossary. This cannot be undone. Its pronunciation terms and translation rules stop applying to anything generated afterwards; videos already generated are unaffected, and requests that still reference it keep working.

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.

Creates a brand kit by importing logos, colors and fonts from a public website; by calling it you confirm you have the rights to use those assets. The kit assembles in the background: poll GET /v3/brand-kits/{brand_kit_id} until status is completed. Send an Idempotency-Key to make retries safe.

Returns one brand kit with its colors, logos and fonts and the role each plays. While status is loading these are provisional; poll every 2 to 5 seconds until status is completed.

Updates a brand kit's name or role assignments: color roles, main logo, heading and body fonts. Omitted fields are unchanged and null is rejected. Each role object you send replaces the existing one in full; {} clears a role and it stays cleared. Role edits return 409 until the kit is completed; shared kits return 403.

Deletes a brand kit and its colors, logos and fonts. This cannot be undone. Videos already rendered with it are unaffected. A kit shared from another workspace cannot be deleted and returns 403.

Generates speech with the voice identified by voice_id, an ACTIVE HeyGen Voice clone in your workspace, and returns a URL to a 44.1 kHz mono WAV file. The request stays open until synthesis finishes. seed, speed, pitch_shift and pitch_variance apply to professional clones only. Rate limit: 30 requests per minute per workspace member.

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

Creates a professional voice from recordings, or retrains one when voice_id is set. The voice is PENDING while training; poll GET /v3/models/audio/voices/{voice_id} until it is ACTIVE or FAILED. A new voice needs a free professional-voice slot; each purchased slot provides five pooled trainings per monthly billing period, including the first, and failed trainings do not count. Send an Idempotency-Key to make retries safe.

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.

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.

Generates a scene with its sound from a prompt using HeyGen Video (heygen-video-1). Set mode to text_to_video, image_to_video or reference_to_video; reference-to-video takes up to twelve references in total, and reference videos must be between 1:4 and 4:1. Returns 202 with a video_id; poll GET /v3/models/videos/{video_id}. Send an Idempotency-Key to retry safely; without one, each submission creates a new generation. To have an avatar speak a script, use POST /v3/videos.

Returns a HeyGen Video generation: pending, processing, completed, failed or cancelled. Completed results include a fresh video_url, duration and dimensions; failed results include failure_code and failure_message. Poll again to refresh an expired URL.

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.60 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.

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).