> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog

> Track every HeyGen API change, new endpoint, deprecation, and version bump in the API changelog. Subscribe via RSS or webhook to get notified on the next.

**HeyGen Voice seed and prosody on instant clones**

Updated - November 2026

**Instant clones take `seed`, `speed` and pitch, and an omitted seed is random**

[`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](https://heygen-1fa696a7.mintlify.site/reference/stream-speech) now apply `seed`, `speed`, `pitch_shift` and `pitch_variance` to instant clones, `heygen-voice-1-turbo` included, as well as to professional clones. Before, instant clones accepted these fields and ignored them. A request without `seed` now gets a random one, so sending the same request again gives a new take instead of the same audio. To try to repeat a result, send the same `seed` again; repeats are best effort. See [request fields](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md#request-fields).

**HyperFrames 4:5 aspect ratio**

Added - November 2026

**Render HyperFrames as a 4:5 portrait feed post**

[`POST /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/reference/create-hyperframes-render) accepts `aspect_ratio: "4:5"` alongside `16:9`, `9:16` and `1:1`. 4:5 is available at `1080p` only; `4:5` with `resolution: "4k"` returns a 400. The default stays `16:9`. [`GET /v3/hyperframes/renders/{render_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-hyperframes-render) and [`GET /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/reference/list-hyperframes-renders) can now return `4:5` in `aspect_ratio`.

**Avatar 6 in the API reference**

Updated - November 2026

**Avatar 6 endpoints and engine options are now documented**

[`POST /v3/models/avatars`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-6-video) animates one reference image or video with speech audio on `heygen-avatar-6` or `heygen-avatar-6-turbo`. [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) accepts the same two engines through `engine`, and Avatar 6 renders at 1080p by default or 2K with `resolution: "2k"`. Check `supported_api_engines` on an avatar look to confirm it can use Avatar 6.

**HyperFrames NTSC frame rates**

Added - November 2026

**Render HyperFrames at 23.976, 29.97 and 59.94 fps**

[`POST /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/reference/create-hyperframes-render) accepts `fps` as `"24000/1001"`, `"30000/1001"` or `"60000/1001"` as well as a whole number from 1 to 240. The default stays 30. [`GET /v3/hyperframes/renders/{render_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-hyperframes-render) and [`GET /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/reference/list-hyperframes-renders) return the exact rate in a new optional `fps_exact` field; it is absent for a whole rate.

**HeyGen Video reference to video up to 30 seconds**

Added - November 2026

**Longer reference-to-video clips, over the API and MCP**

[`POST /v3/models/videos`](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video#duration-limits) accepts whole-second durations from 5 to 30 for `reference_to_video` with `turbo` or `quality` enhancement, at 480p, 768p, 1080p, or 2K. The model ID and endpoint are unchanged. Reference videos keep their 15-second input budget. `duration: "auto"` selects 8–15 seconds for reference to video; set an explicit duration for a longer clip.

The MCP `text_to_video`, `image_to_video` and `reference_to_video` tools accept 5–30 seconds on all plans, with auto capped at 15. `prompt_enhancement` takes `turbo`, `quality`, `ultraquality` or `disabled`. See [Duration limits](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md#duration-limits).

**HeyGen Voice pronunciation**

Added - November 2026

**Set how a voice says names and terms, and send up to 10,000 characters**

[`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](https://heygen-1fa696a7.mintlify.site/reference/stream-speech) accept IPA pronunciations for public and instant voices on `heygen-voice-1` and `heygen-voice-1-turbo`. Send `pronunciation_dictionary` for up to 100 terms, or wrap one occurrence in `<pron ipa="/ʃɪˈvɔːn/">Siobhan</pron>`. `text` now takes up to 10,000 characters on both endpoints and on each WebSocket context. See [Pronunciation](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md#pronunciation).

**Validation error field paths**

Fixed - November 2026

**`error.param` names the field in your request**

v3 validation errors now report the correct field path in `error.param` for fields inside typed objects, for example `video.url` instead of `video.url.url`. Status codes and error codes are unchanged.

**WebSocket input streaming**

Added - November 2026

**Stream text into speech over a WebSocket**

Send text in pieces, such as LLM tokens, and receive audio on one connection. Use `/v3/models/audio/tts/stream-input` for one synthesis, or `/v3/models/audio/tts/multi-stream-input` for up to five contexts. Public and instant voices work on all three HeyGen Voice models, including Turbo Free. Browsers connect with a single-use token from [`POST /v3/models/audio/tts/stream-input/tokens`](https://heygen-1fa696a7.mintlify.site/reference/create-speech-input-token). See [WebSocket input streaming](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md#websocket-input-streaming).

**Direct upload to S3**

Updated - November 2026

**Upload large files straight to S3, now with its own guide**

[`POST /v3/assets/direct-uploads`](https://heygen-1fa696a7.mintlify.site/reference/create-asset-upload) takes video, image, PDF, and SRT files up to 200 MB, audio up to 1.5 GB, and HyperFrames project zips up to 1 GiB. Accepted types include MOV, WebP, HEIC, and WebM audio. Pass `checksum_sha256` to have S3 verify the bytes on upload. See [Direct Upload to S3](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md), and the [Assets overview](https://heygen-1fa696a7.mintlify.site/assets.md) to pick an upload method.

**Speech output formats**

Added - November 2026

**Choose the audio format for speech**

[`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](https://heygen-1fa696a7.mintlify.site/reference/stream-speech) accept `output_format`: `pcm`, `mp3`, `ulaw`, or `alaw`, at a sample rate from 8 kHz to 48 kHz. With `output_format`, the stream returns raw audio bytes instead of SSE. See [Output format](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md#output-format).

**Edit Video**

Added - November 2026

**Edit a rendered video and re-render only what changed**

`POST /v3/videos/{video_id}` changes a video's script text, voice, or avatar engine and motion prompt, keyed by the ids from [`GET /v3/videos/{video_id}/scenes`](https://heygen-1fa696a7.mintlify.site/reference/get-video-scenes). The video keeps its `video_id`, and only the scenes you change render and bill. See [Edit Video](https://heygen-1fa696a7.mintlify.site/edit-video.md).

**HeyGen Voice audio tags**

Added - November 2026

**Tell a voice how to speak a line**

[`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](https://heygen-1fa696a7.mintlify.site/reference/stream-speech) now accept audio tags in `text`, such as `[whispers]` or `[laughs]`. Public and instant voices perform them on all three HeyGen Voice models. Professional voices do not perform them. 201 tags are supported. See [Audio Tags](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-audio-tags.md).

**Cinematic Avatar on HeyGen Video**

Added - November 2026

**Render Cinematic Avatar shots with HeyGen Video**

[`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) with `type: "cinematic_avatar"` now accepts `"model": "heygen_video_1"`. Your avatar looks and their voices become the cast of a HeyGen Video shot: 16:9 or 9:16, 720p, 5 to 15 seconds, with up to 3 audio references alongside images and videos. See [Cinematic Avatar](https://heygen-1fa696a7.mintlify.site/cinematic-avatar.md).

**Shared reference-video budget**

Updated - October 2026

**Use up to 15 seconds of reference footage across a request**

For `reference_to_video` on [`POST /v3/models/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-heygen-video), up to three reference videos share a 15-second input budget. A single video can use all 15 seconds. When the combined footage exceeds the budget, each video keeps up to its first five seconds and the remaining time is shared equally among videos with footage left: two 10-second videos use 7.5 seconds each.

`input_video_duration` in submission and polling responses reports the allocated total used for billing. This input budget is separate from output `duration`. See [References and prompt labels](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md#references-and-prompt-labels).

**Avatar V blinking**

Added - October 2026

**More natural blinking for Avatar V**

[`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) now accepts `"more_blinking": true` in `engine` for Avatar V, for avatars that blink too little. See [Avatar V](https://heygen-1fa696a7.mintlify.site/avatar-v.md).

**One brand glossary per workspace**

Updated - October 2026

**Update your glossary instead of creating another**

[`POST /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/create-brand-glossary) now returns `409 conflict` when the workspace already has a glossary. Existing glossaries keep working. To change rules, update the glossary with [`PATCH /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-brand-glossary). See [Brand Glossary](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary/manage.md#create).

**HeyGen Video up to 30 seconds**

Added - October 2026

**Longer text-to-video and image-to-video clips**

[`POST /v3/models/videos`](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video#duration-limits) accepts whole-second durations from 5 to 30 for `text_to_video` and `image_to_video` with `turbo` or `quality` enhancement, at 480p, 768p, 1080p, or 2K. The model ID and endpoint are unchanged. `duration: "auto"` now selects 8–30 seconds for these settings; omitting duration still selects 5 seconds.

Reference-to-video, `disabled` or `ultraquality` enhancement, and MCP requests remain limited to 15 seconds. Auto duration respects those limits. See [Duration limits](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md#duration-limits).

**HeyGen Video auto duration**

Added - October 2026

**Let HeyGen Video pick the clip length**

[`POST /v3/models/videos`](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video) now accepts `"duration": "auto"`. HeyGen picks a length from 8 to 15 seconds based on quoted dialogue, so spoken lines land at a natural pace. The completed job reports the resolved `duration`, and billing uses that length. See [Auto duration](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md#auto-duration).

**Speech to speech**

Added - October 2026

**Speak a recording again in one of your voices**

[`POST /v3/models/audio/sts`](https://heygen-1fa696a7.mintlify.site/docs/voices/speech-to-speech) takes a recording of up to 300 seconds and returns the same speech, with the same words and timing, in an instant voice from your workspace. The call returns one WAV. See [Speech to Speech](https://heygen-1fa696a7.mintlify.site/docs/voices/speech-to-speech.md).

**Professional voices without a language**

Updated - October 2026

**`language` is optional for professional voices**

[`POST /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/create-or-retrain-an-audio-voice) in `professional` mode no longer needs `language`. Leave it out and training detects the language of each recording. The voice's `language` is `null` until it is `ACTIVE`. See [Professional Voice Clone](https://heygen-1fa696a7.mintlify.site/docs/voices/professional-voice-clone.md).

**HeyGen Voice previews**

Added - October 2026

**Listen to a voice before you use it**

[`GET /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices) and [`GET /v3/models/audio/voices/{voice_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-an-audio-voice) now return `preview_audio_url` for every `ACTIVE` voice: instant, professional and public. It is a URL to a WAV of the voice reading a short preview script in its language. The URL can expire, so read the voice again rather than storing it. See [Instant Voice Clone](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-instant-clone.md#manage-voices).

**Instant voices from an image**

Added - October 2026

**Give an instant voice the sound of a setting**

[`POST /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/create-or-retrain-an-audio-voice) in `instant` mode now accepts `image`: a picture of the speaker in their setting. The voice takes on the ambience of the image's background, so a quiet room keeps it clean and a busy street adds matching background sound. `image` cannot be combined with `gender` or `age`. See [Instant Voice Clone](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-instant-clone.md).

**HeyGen Voice public voices and batch timestamps**

Added - October 2026

**Public voices, and character timestamps on completed speech**

* [`GET /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices) takes `type`: `private` (default) lists your workspace's voices, and `public` lists HeyGen's public voices. Any workspace can read a public voice with [`GET /v3/models/audio/voices/{voice_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-an-audio-voice) and speak it on [`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](https://heygen-1fa696a7.mintlify.site/reference/stream-speech). Public voices can't be deleted.
* [`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) now accepts `with_timestamps`. When `true`, the response adds `original_characters` with the start and end time of each character. See [Character timestamps](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md#character-timestamps).

**Language-specific brand glossary rules**

Added - October 2026

**Set pronunciations and forced translations per language**

[`POST`](https://heygen-1fa696a7.mintlify.site/reference/create-brand-glossary) and [`PATCH /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/update-brand-glossary) now accept `pronunciation_language` on `terms` entries and `target_language` on `forced_translations` entries, as `{ "scope": "specific", "code": "fr" }` or `{ "scope": "all" }`.

* Omit the field for an all-languages rule. Existing requests and responses are unchanged.
* A language-specific rule takes precedence over an all-languages rule for that language.
* The same term can appear once per language in each list.
* A term in both `do_not_translate_terms` and `forced_translations` stays untranslated.
* See [Brand Glossary](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary/pronunciations.md#per-language-pronunciations).

**HeyGen Voice 1 Turbo**

Added - October 2026

**Faster, cheaper speech for instant voices**

[`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](https://heygen-1fa696a7.mintlify.site/reference/stream-speech) now accept `"model": "heygen-voice-1-turbo"`. Turbo speaks instant voices at lower latency; `heygen-voice-1` stays the default. Professional voices speak through `heygen-voice-1`. See [Text to Speech](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md).

**HeyGen Voice Instant Clone and Text to Speech**

Added - October 2026

**Instant voices on the HeyGen Voice model**

[`POST /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/create-or-retrain-an-audio-voice) now takes `"mode": "instant"`: one recording in, a HeyGen Voice `voice_id` out, usually `ACTIVE` within seconds. No training and no voice clone slot. See [Instant Voice Clone](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-instant-clone.md).

* `mode` is now required on every create and retrain call: `instant` or `professional`.
* List, get, and delete on `/v3/models/audio/voices` cover both kinds; `mode` tells them apart.
* [`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](https://heygen-1fa696a7.mintlify.site/reference/stream-speech) speak instant voices too. `model` defaults to `heygen-voice-1`; `expressiveness_boost` (`0.0`–`1.0`) is instant-only; `seed`, `speed`, `pitch_shift`, `pitch_variance`, and `<break>` pauses stay professional-only. See [Text to Speech](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md).
* Creating an instant voice is free during the preview.

**HeyGen Video 1080p**

Added - October 2026

**Render HeyGen Video at 1080p**

[`POST /v3/models/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-heygen-video) now accepts `resolution: "1080p"` alongside `480p`, `768p` and `2k`. The default stays `768p`.

* `1080p` bills at the `2k` rate: 3× the `768p` rate, for output seconds and reference-video seconds alike.
* `16:9` returns 1890 × 1080 and `9:16` returns 1080 × 1890.
* `text_to_video` and `reference_to_video` render `1080p` in `16:9` or `9:16`, the same as `2k`. Set `aspect_ratio` explicitly for `reference_to_video`, which otherwise defaults to `adaptive`.
* `image_to_video` follows the first frame at every resolution.
* See [HeyGen Video](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md) for the full parameter reference.

**Higher rate limits for Enterprise**

Changed - October 2026

**Enterprise workspaces get higher request-rate limits**

Request-rate limits now depend on your plan. Pay-As-You-Go and subscription limits are unchanged. Workspaces on an Enterprise API plan get higher limits per user and endpoint:

* **Read:** 1,000 per minute (was 300).
* **Write:** 30 per second (was 10).
* **Heavy:** 120 per minute (was 30).
* **Status polling:** 1,500 per minute (was 500), and 1,800 per minute per IP address (was 600).
* Enterprise workspaces can ask their account team for custom limits on specific endpoints.
* A rate-limit `429` now carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `X-RateLimit-Scope` alongside `Retry-After`.
* See [Usage Limits](https://heygen-1fa696a7.mintlify.site/docs/usage-limits.md#rate-limiting) for which endpoints fall in each type and the endpoints with fixed limits.

**HeyGen Video 2K**

Added - October 2026

**Render HeyGen Video at 2K**

[`POST /v3/models/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-heygen-video) now accepts `resolution: "2k"` alongside `480p` and `768p`. The default stays `768p`.

* `2k` bills at 3× the `768p` rate, for output seconds and reference-video seconds alike.
* `text_to_video` and `reference_to_video` render `2k` in `16:9` or `9:16`. Set `aspect_ratio` explicitly for `reference_to_video`, which otherwise defaults to `adaptive`.
* `image_to_video` follows the first frame at every resolution.
* See [HeyGen Video](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md) for the full parameter reference.

**Create Studio Templates via API**

Added - October 2026

**Turn a video into a template and mark what changes, without opening the editor**

New endpoints for creating Studio templates over the API. Make one video, promote it to a template, declare its variables, then generate a video per viewer with the existing [`POST /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template).

* [`POST /v3/templates`](https://heygen-1fa696a7.mintlify.site/reference/create-template-from-video) creates a private template from a video you generated with `POST /v3/videos` or saved in the HeyGen editor.
* [`GET /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-template) now returns `composition`, every part of each scene with its `id` and `bindable_as`, plus an `edit_version`.
* [`PUT /v3/templates/{template_id}/variables`](https://heygen-1fa696a7.mintlify.site/reference/set-template-variables) sets the full variable list. Bind avatars, voices, images, video and audio to a part by `element_id`, and turn exact phrases into `{{name}}` placeholders with `match`. Send `expected_edit_version` to get `409` `stale_edit_version` instead of overwriting a concurrent change.
* [`PATCH /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-template) renames a template and [`DELETE /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-template) removes it.
* Character variables take `avatar_id`. `avatar_look_id` and `character_id` are still accepted.
* **Deprecations, removed on October 31, 2026:** the `avatar_look_id`, `character_id` and `character_type` names on character variables (send and read `avatar_id`), and the older `scenes` field on `GET /v3/templates/{template_id}` (read `composition.scenes`). `scene_ids` is unaffected. Until then both names are accepted and echoed, and `scenes` keeps its current shape.
* See the new [Create Studio Template via API](https://heygen-1fa696a7.mintlify.site/create-template.md) guide.

**HeyGen Video API**

Added - September 2026

**Generate a short video from a prompt, a first frame, or reference media**

The public API reference now includes [`POST /v3/models/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-heygen-video) and [`GET /v3/models/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-heygen-video) for the `heygen-video-1` model.

* Choose `text_to_video`, `image_to_video`, or `reference_to_video` with `mode`. Generate 5–15 second videos at 480p or 768p with a prompt of up to 5,000 characters.
* Image-to-video follows the first frame's proportions. Reference-to-video requires at least one image or video and accepts up to nine images, three videos, and three audio recordings, with twelve references total.
* Creation returns `202` with a `video_id`. Poll the status endpoint until `completed`, `failed`, or `cancelled`; completed results include a download URL, and unsuccessful results include failure details.
* Send an `Idempotency-Key` header when submitting so a retry does not start a second generation. API keys need `videos:write` to create and `videos:read` to poll.

**Assets Library Folder Support**

Changed - September 2026

**Recognize Assets library folders when reading and placing results**

[`GET /v3/folders/{folder_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-folder) documents `asset` alongside `mixed`, `video`, and `video_translate` folder types. Existing Assets library folder IDs are also accepted by routes with a `folder_id` destination.

* Assets library folders are created in the HeyGen app and are flat: [`POST /v3/folders`](https://heygen-1fa696a7.mintlify.site/reference/create-folder) cannot create them or nest another folder inside them.
* The HeyGen app displays only assets in Assets library folders, so a video or translation placed there may not appear in that view.

**Folders on v3**

Added - September 2026

**Create folders and file outputs into them over the API**

New endpoints: [`POST /v3/folders`](https://heygen-1fa696a7.mintlify.site/reference/create-folder) creates a folder, and [`GET /v3/folders/{folder_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-folder) returns one so a stored id can be checked before use. This is the v3 successor to `POST /v1/folders/create`.

* Send `name` (1 to 256 characters) and an optional `parent_id` to nest the folder inside another one. Leave `parent_id` out to create it at the workspace root. Build a tree one level at a time, passing each new `folder_id` as the next `parent_id`.
* `type` is `mixed` (the default, same as the web app's New folder action), `video`, or `video_translate`. Every type accepts videos and translations.
* Pass the returned `folder_id` on [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video), [`POST /v3/video-translations`](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation), [`POST /v3/video-translations/proofreads`](https://heygen-1fa696a7.mintlify.site/reference/create-proofread-session), [`POST /v3/lipsyncs`](https://heygen-1fa696a7.mintlify.site/reference/create-lipsync), or [`POST /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template) to place the output in that folder. A `folder_id` outside your workspace is rejected.
* Send an `Idempotency-Key` header so a retried create does not leave a duplicate folder behind.

**Professional Voice Pause Tags**

Changed - September 2026

**Use explicit pauses with a professional HeyGen voice clone**

The text input documentation for [`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) and [`POST /v3/models/audio/tts/stream`](https://heygen-1fa696a7.mintlify.site/reference/stream-speech) now clarifies support for `<break time="0.5s"/>` with professional voice clones. Pause values are in seconds, with a maximum of five seconds per pause; other SSML tags and break tags for instant voice clones are unsupported.

**Scene-Scoped Edits for Video Agent**

Added - September 2026

**Revise the scenes you name and keep the rest**

[`POST /v3/video-agents/{session_id}`](https://heygen-1fa696a7.mintlify.site/reference/send-message-or-request-revision) now accepts an `edit_plan`: one natural-language change per scene, applied together in a single turn. Untouched scenes keep their script and visuals, so a two-scene fix stays a two-scene fix.

* Read scene ids and the document's `edit_version` from [`GET /v3/videos/{video_id}/scenes`](https://heygen-1fa696a7.mintlify.site/reference/get-video-scenes), then send each item with its `scene_id`, `text`, `scene_snapshot_video_id`, and `edit_version`. `message` is optional when a plan is sent.
* Works on sessions created in `generate` or `chat` mode. The response returns the new working draft in `video_id`; poll [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) for status.
* The whole plan is validated before submission: a scene outside the snapshot returns `400` `invalid_parameter`, and a snapshot that changed since it was read returns `409` `stale_edit_version`. Up to 50 items per request.
* See the new [Edit Scenes](https://heygen-1fa696a7.mintlify.site/docs/edit-scenes.md) guide, with a before/after example.

**Look Packs over the API**

Added - September 2026

**Dress an avatar you already own in a curated set of looks**

New endpoint: [`POST /v3/avatars/looks`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-looks) generates new looks for an existing avatar. Pass one look you own as `reference_look_id` and a curated `template_id`; the results join that look's character. Their ids are returned immediately, but video generation must wait for the looks to finish processing.

* `type: "look_pack"` applies a Look Pack, a curated set built around one theme, and the pack decides how many looks it produces. Generation is 16:9, and `aspect_ratio: "9:16"` center-crops the delivered frames to portrait.
* `type: "template"` restyles the reference look into a single look template, returning two looks in the template's aspect ratio.
* Public templates work for every workspace; enterprise custom packs assigned to a workspace work the same way on this endpoint.
* The response returns the character as `group_id` and one id per look. Poll [`GET /v3/avatars/looks/{look_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-avatar-look) until each reports `completed` or `failed`.
* Send an `Idempotency-Key` header so a retry cannot start a second run: a retry while the original is in flight returns `409` `request_in_progress`, and one after it finishes replays the original response.
* See the new [Look Packs and Templates](https://heygen-1fa696a7.mintlify.site/docs/avatar-look-packs.md) guide.

**Avatar Creation Guides**

Changed - September 2026

**One guide per creation path**

The Create Avatar guide is now a router into four focused guides: [Video to Avatar](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-video.md), [Photo to Avatar](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-photo.md), [Prompt to Avatar](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-prompt.md), and [Look Packs and Templates](https://heygen-1fa696a7.mintlify.site/docs/avatar-look-packs.md). Each one carries the request, the polling loop, the failure codes, and the render step for that path. [Create Avatar](https://heygen-1fa696a7.mintlify.site/docs/create-avatar.md) keeps the shared response shape and the avatars-versus-looks model.

**API Key Introspection, Avatar Default Voice, Housekeeping Endpoints**

Added - September 2026

**Inspect your key, set an avatar's default voice, and clean up glossaries and proofread sessions**

* [`GET /v3/api_keys/self`](https://heygen-1fa696a7.mintlify.site/reference/get-current-api-key) returns the name, `scope_mode`, `scopes`, and expiration of the key making the request. Works with any key. See [API Key](https://heygen-1fa696a7.mintlify.site/docs/api-key.md#restricting-key-permissions).
* [`PATCH /v3/avatars/{group_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-avatar-group) sets `default_voice_id` on an avatar you own. See [Avatars](https://heygen-1fa696a7.mintlify.site/docs/avatars.md#get-a-single-avatar-group).
* [`DELETE /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-brand-glossary) removes a glossary. See [Brand Glossary](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary/manage.md#delete).
* [`GET /v3/video-translations/proofreads`](https://heygen-1fa696a7.mintlify.site/reference/list-proofread-sessions) lists proofread sessions and [`DELETE /v3/video-translations/proofreads/{proofread_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-proofread-session) removes one. See [Video Translation Precision](https://heygen-1fa696a7.mintlify.site/docs/video-translation-precision.md#list-and-delete-proofread-sessions).

**Burst Concurrency**

Added - September 2026

**Run above your included concurrency on demand**

Enterprise workspaces can now turn on burst instead of buying a higher permanent concurrency cap. Set an extra cap of up to +50 under **Capacity → Concurrency** in [Usage](https://app.heygen.com/developers/usage). The cap applies to avatar renders and video translations separately, so [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) and [`POST /v3/video-translations`](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation) each accept requests up to *included + extra* concurrent workflows of their type before returning `429`.

* Workflows admitted while every included slot is busy bill at **1.5×** your contract rate; workflows that land in an included slot bill at the normal rate. You only pay the premium for workflows that actually burst.
* Burst workflows are tagged **Burst** in the [Activity tab](https://app.heygen.com/developers/usage?tab=activity), and a Burst panel in the Usage sidebar totals the premium for the period.
* Burst is shared across the web app and the API. It is enabled per workspace by your account team; see [Burst Concurrency](https://heygen-1fa696a7.mintlify.site/docs/burst.md) and the updated [Usage Limits](https://heygen-1fa696a7.mintlify.site/docs/usage-limits.md#concurrency-limits).

**Translation Rules on Brand Glossaries**

Added - September 2026

**Set do-not-translate terms and forced translations over the API**

[`POST /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/create-brand-glossary) and [`PATCH /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-brand-glossary) now accept two translation lists alongside `terms`:

* `do_not_translate_terms`: `[{ "term": "HeyGen" }]` keeps each term untranslated in every target language.
* `forced_translations`: `[{ "term": "CEO", "translation": "Geschäftsführer" }]` replaces each term with its exact translation, inserted verbatim.
* Both lists behave like `terms` on `PATCH`: send a list to replace it, an empty list to clear it, omit it to leave it alone. [`GET /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-brand-glossary) returns them whenever a glossary has rules, including glossaries set up in the HeyGen app.
* The rules apply whenever the glossary is used by a translation feature: over the API on [video translation](https://heygen-1fa696a7.mintlify.site/docs/video-translate.md), and in the HeyGen app when a Studio or Video Agent draft is translated. Plain video generation and text-to-speech use `terms` alone. Tone settings stay managed in the HeyGen app.
* Migrating off `/v1/brand_voice` before the October 31, 2026 sunset: `vocabulary` maps to `terms`, `blacklist` to `do_not_translate_terms`, `whitelist` to `forced_translations`. See the [mapping table](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary/manage.md#migrating-from-v1-brand-voice).

**HeyGen Professional Voice Clone**

Added - September 2026

**Train a studio-grade voice clone on the HeyGen Voice model**

Professional voice cloning is now available on the [HeyGen Voice](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-voice.md) model, HeyGen's in-house voice model. Train a dedicated voice adapter from 1–10 recordings of the same speaker totaling 20+ minutes, then generate speech with it.

* `POST /v3/models/audio/voices` creates a voice, or retrains an existing one when `voice_id` is supplied. Poll `GET /v3/models/audio/voices/{voice_id}` until `status` is `ACTIVE`. See [HeyGen Professional Clone](https://heygen-1fa696a7.mintlify.site/docs/voices/professional-voice-clone.md).
* `POST /v3/models/audio/tts` returns one completed 44.1 kHz WAV; `POST /v3/models/audio/tts/stream` streams ordered audio parts over Server-Sent Events with optional word timestamps. See [HeyGen Voice Speech](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-speech.md).
* This is a paid feature: each voice occupies a purchased professional voice clone slot, bought on the [Usage page](https://platform.heygen.com/usage). Each slot includes five trainings per monthly billing period, and synthesis bills at 0.6 API credits per generated minute. A voice beyond the workspace's slot limit returns `voice_expired` until a slot is added.
* For a clone from a single short recording, HeyGen Instant Clone remains available to all API plans.

**Brand Glossaries for Video Agent**

Added - August 2026

**Brand the look and the narration in one request**

[`POST /v3/video-agents`](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session) now accepts `brand_glossary_id`, so the narration the agent writes and voices pronounces your terms your way — the same field already accepted by [Studio](https://heygen-1fa696a7.mintlify.site/studio-videos.md), [Templates](https://heygen-1fa696a7.mintlify.site/templates.md), and [Video Translate](https://heygen-1fa696a7.mintlify.site/docs/video-translate.md) requests.

* Combines with `brand_kit_id` on the same request, making Video Agent the one endpoint that takes both: the kit shapes what you see, the glossary shapes what you hear.
* The glossary is set at session creation and covers the whole session; a follow-up message in an [interactive session](https://heygen-1fa696a7.mintlify.site/docs/interactive-sessions.md) can swap the brand kit but not the glossary.
* Pronunciation affects the synthesized audio only — captions and subtitles keep the original spelling. See [Brand Glossary](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary.md) and [Apply a Glossary](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary/apply.md).

**Read a Video's Scenes**

Added - August 2026

**Inspect the full composition behind any video id**

New endpoint: [`GET /v3/videos/{video_id}/scenes`](https://heygen-1fa696a7.mintlify.site/reference/get-video-scenes) returns a video's scene-by-scene composition — what each scene shows and says — together with the video-level context needed to read it (title, aspect ratio, resolution, captions, brand glossary).

* Works for any video in your workspace, whichever surface created it: a [studio request](https://heygen-1fa696a7.mintlify.site/studio-videos.md), a [template render](https://heygen-1fa696a7.mintlify.site/templates.md), an [avatar video](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md), or a video composed by hand in the editor. It describes the video as it stands now, including editor changes made after creation.
* Each scene splits by role: `background` fills the frame, `elements` are placed within it, `script` is the audio over it — synthesized speech (verbatim text, voice id, voice settings), uploaded audio, or a held silence. Walking `scenes[].script[].text` yields the full narration in playback order.
* Element types are an open set: `avatar`, `image`, and `video` are described in full, containers carry their children, and other types arrive as placeholders to skip.
* See the new [Video Details](https://heygen-1fa696a7.mintlify.site/video-details.md) guide for how this pairs with [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) — which now returns the full deliverable set: `gif_url`, `captioned_video_url`, `subtitle_url`, `completed_at`, `folder_id`, `video_page_url`, and failure details alongside the MP4 and thumbnail.

**Update and Delete Brand Kits**

Added - August 2026

**Correct a kit's role assignments, or remove the kit**

* [`PATCH /v3/brand-kits/{brand_kit_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-brand-kit) sets `name`, `color_roles`, `logo_roles`, and `font_roles`. An omitted field is left unchanged; a role object you send replaces the stored one in full. Role edits need an assembled kit and return `409` while `status` is `loading`.
* [`DELETE /v3/brand-kits/{brand_kit_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-brand-kit) removes a kit and the colors, logos, and fonts it holds. Videos already generated keep their branding.
* The colors, logos, and font files themselves stay curated in the HeyGen app, where a kit keeps its `brand_kit_id`. See [Brand Kits](https://heygen-1fa696a7.mintlify.site/docs/brand-kits.md).

**Create Brand Kits from a Website**

Added - August 2026

**Import a brand's logos, colors, and fonts over the API**

[`POST /v3/brand-kits`](https://heygen-1fa696a7.mintlify.site/reference/create-brand-kit) builds a brand kit from a public website URL, so a workspace can go from a domain to on-brand [Video Agent](https://heygen-1fa696a7.mintlify.site/docs/video-agent.md) output without opening the HeyGen app.

* The response returns a `brand_kit_id` that is usable immediately with `status: "loading"`. Poll [`GET /v3/brand-kits/{brand_kit_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-brand-kit) every 2 to 5 seconds until `status` is `completed` before relying on the imported colors, logos, or fonts.
* The detail response adds `color_roles`, `logo_roles`, and `font_roles`, naming which asset plays which part in the brand's visual system.
* Send an `Idempotency-Key` header to make retries safe. See [Brand Kits](https://heygen-1fa696a7.mintlify.site/docs/brand-kits.md).

**Create and Update Brand Glossaries**

Added - August 2026

**Manage custom pronunciations programmatically**

Brand glossaries can now be created and edited over the API, so a per-tenant vocabulary can be provisioned and kept in sync from your own system.

* [`POST /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/create-brand-glossary) creates a glossary from a `name` and an optional list of `terms`. Names are unique per workspace, compared without regard to case; a duplicate returns `409`.
* [`PATCH /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/update-brand-glossary) replaces `name` or `terms` in full — an omitted field is untouched, and an empty `terms` array clears the list.
* Translation rules stay managed in the HeyGen web app and are never modified by an update made here. See [Brand Glossary](https://heygen-1fa696a7.mintlify.site/docs/brand-glossary.md).

**Consent Video Upload Available for All Enterprise Accounts**

Changed - August 2026

**Level 2 consent is no longer gated behind a whitelist**

Uploading a pre-recorded consent video (Level 2) is now available to every Enterprise account. Previously the flow required whitelisting; that gate has been removed.

* Enterprise customers can send `consent_video` on [`POST /v3/avatars/{group_id}/consent`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-consent) without requesting access first.
* The webcam flow (Level 1) is unchanged and remains available to all customers. Skip-consent (Level 3) still requires an indemnity agreement — [contact sales](https://www.heygen.com/contact-us/sales).
* See [Avatar Consent](https://heygen-1fa696a7.mintlify.site/docs/avatar-consent.md) for the three levels and the required consent statement.

**Brand Glossaries for Avatar and Image Videos**

Added - August 2026

**Apply custom pronunciations to direct video-creation requests**

[`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) and [`POST /v3/videos/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-batch) now accept `brand_glossary_id` for both `"type": "avatar"` and `"type": "image"` payloads.

* The glossary applies when HeyGen synthesizes audio from a `script`; caller-supplied `audio_url` and `audio_asset_id` inputs are unchanged.
* Custom pronunciations affect generated speech only. Captions and subtitle files retain the script's original spelling.
* Discover available IDs with [`GET /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/list-brand-glossaries), then inspect individual term mappings with [`GET /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-brand-glossary).

**Captions Always Available for Translations and Lipsyncs**

Changed - August 2026

**Caption sidecars are generated for every completed job**

Caption-generation flags on video translation and lipsync requests are now deprecated and ignored. Captions are always generated; clients choose whether to display or download them.

* `enable_caption` is deprecated on `POST /v3/video-translations`, `POST /v3/video-translations/batches`, `POST /v3/lipsyncs`, and `POST /v3/lipsyncs/batches`.
* The `captions` flag is likewise deprecated when generating a video from a completed translation proofread.
* Completed video-translation responses expose their SRT and VTT caption URLs regardless of the submitted flag. Existing requests remain compatible.

**Avatar V Photo Fallback**

Changed - August 2026

**Photo avatars can render without an animation-reference look**

When an Avatar V photo avatar's group has no eligible digital-twin or curated reference look, video creation now renders directly from the photo instead of rejecting the request.

* The fallback works when `reference_look_id` is omitted and no eligible look can be selected automatically.
* `motion_prompt` still requires an animation reference for Avatar V photo avatars. Supply an eligible reference look when you need prompted body motion or hand gestures.

**Brand Glossary on Studio Videos**

Added - July 2026

**Control how custom terms are pronounced, and read a glossary's terms over the API**

A brand glossary maps a term to how it should be spoken, such as `HeyGen` as `hey-jen`. Two additions and one rename cleanup:

* **[HeyGen Studio](https://heygen-1fa696a7.mintlify.site/studio-videos.md) accepts `brand_glossary_id`.** Pass it on a `"type": "studio"` request to apply the glossary to every scene whose audio is synthesized from a `script`. Scenes that supply their own `audio_url` or `audio_asset_id` are unaffected. Pronunciations change the generated audio only: captions and the `.srt` sidecar keep the original spelling.
* **New endpoint: [`GET /v3/brand-glossaries/{brand_glossary_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-brand-glossary).** Returns a glossary with its full term list, so you can confirm exactly which terms are remapped and how. Previously [`GET /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/list-brand-glossaries) could tell you a glossary existed but not what was in it.
* **`brand_voice_id` is now deprecated in favor of `brand_glossary_id`** across the v3 endpoints that accept it, including [`POST /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template), which now accepts both names. Existing requests keep working, since `brand_voice_id` continues to resolve to the same glossary.

**Video Agent Powered by Hyperframes**

Changed - July 2026

**Every Video Agent scene is now composed and rendered with Hyperframes**

The [Video Agent](https://heygen-1fa696a7.mintlify.site/docs/video-agent.md) now authors every animated stat, chart, caption, and scene transition as a [Hyperframes](https://heygen-1fa696a7.mintlify.site/hyperframes-overview.md) composition — scenes are built in code, not assembled from a fixed template set. In practice, that means the agent can produce any look you can describe: pass a `style_id` for a curated preset, or write a **style paragraph** in your prompt and the agent renders to it literally.

* New guide: [Prompting Guide](https://heygen-1fa696a7.mintlify.site/docs/prompting-guide.md) — how to write a prompt that lands on the first cut, including the anatomy of a style paragraph (name, palette, art direction, motion, transitions, vibe).
* Updated [Prompt to Video](https://heygen-1fa696a7.mintlify.site/docs/video-agent.md) to document the Hyperframes-powered rendering path.
* No API changes required — existing [`POST /v3/video-agents`](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session) requests automatically benefit.

**Studio Video-Scene Voiceover**

Added - July 2026

**Narrate over an existing clip and control how it fills the scene**

`video` scenes in a [HeyGen Studio](https://heygen-1fa696a7.mintlify.site/studio-videos.md) request now accept an optional voiceover — the same audio inputs a narrated `image` scene takes (`script` + `voice_id`, `audio_url`, or `audio_asset_id`). When present, the voiceover drives the scene's duration instead of the clip's own length.

* **Scene-duration alignment:** a new `playback.mode` chooses how the clip fills the voiceover-driven duration — `freeze` (hold the last frame, the default), `loop` (repeat the clip), or `fit_to_scene` (adjust playback speed to end exactly with the voiceover).
* The voiceover and the clip's own audio compose: keep using `playback.volume` / `mute` to bring the clip down under narration.
* See [Video Scenes](https://heygen-1fa696a7.mintlify.site/studio-videos.md#video-scenes) in the HeyGen Studio guide.

**HeyGen Studio Scene Composition**

Added - July 2026

**Compose avatar clips, images, and video footage into one video with a single API call**

[`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) accepts a new creation mode, `"type": "studio"` — send an ordered list of whole-frame scenes and get back one rendered MP4. HeyGen owns the layout: every scene is rendered onto one global output canvas, scene durations are derived server-side, and a single `video_id` tracks the all-or-nothing render.

* New guide: [HeyGen Studio](https://heygen-1fa696a7.mintlify.site/studio-videos.md) under Video Composition.
* **Three scene types**, mixable in one request (1–50 scenes): `avatar_video` (an avatar or lip-synced image speaking a script or audio track, with engine selection, motion prompts, and solid-color backgrounds), `image` (a still held for a set `duration` or narrated), and `video` (an existing clip, with `playback` volume/mute control).
* **Global output settings** set once per request: `aspect_ratio`, `resolution`, captions (sidecar `subtitle_url` plus optional burn-in), and webhooks.
* **Not available in batches:** a studio request already composes many scenes into one video, so `"type": "studio"` is not accepted by [`POST /v3/videos/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-batch). Send studio videos one per request.

**Batch APIs for Translations, Lipsyncs, and Assets**

Added - July 2026

**Every high-volume workflow now has a native batch API**

Batch creation, introduced for [videos](https://heygen-1fa696a7.mintlify.site/batch-videos.md), now covers video translations, lipsyncs, and asset uploads. Each accepts up to 100 payloads per call, returns a single `batch_id`, processes items independently (one bad item does not fail the rest), and supports `Idempotency-Key` retries.

* New guides under Batches: [Video Translations](https://heygen-1fa696a7.mintlify.site/batch-video-translations.md), [Lipsyncs](https://heygen-1fa696a7.mintlify.site/batch-lipsyncs.md), and [Assets](https://heygen-1fa696a7.mintlify.site/batch-assets.md).
* **Translations:** [`POST /v3/video-translations/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation-batch) — a payload targeting multiple `output_languages` expands to one item per language. Replaces the CSV-script workflow previously documented as Bulk Video Translation.
* **Lipsyncs:** [`POST /v3/lipsyncs/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-lipsync-batch) — payloads identical in shape to `POST /v3/lipsyncs`.
* **Assets:** [`POST /v3/assets/direct-uploads/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-asset-upload-batch) presigns up to 100 direct-to-S3 slots in one call; finalize with [`POST /v3/assets/complete/batches`](https://heygen-1fa696a7.mintlify.site/reference/complete-asset-upload-batch).
* **Bulk status checks:** [`GET /v3/video-translations/statuses`](https://heygen-1fa696a7.mintlify.site/reference/bulk-video-translation-statuses), [`GET /v3/lipsyncs/statuses`](https://heygen-1fa696a7.mintlify.site/reference/bulk-lipsync-statuses), [`GET /v3/assets/statuses`](https://heygen-1fa696a7.mintlify.site/reference/bulk-asset-statuses), and [`GET /v3/videos/statuses`](https://heygen-1fa696a7.mintlify.site/reference/bulk-video-statuses) — up to 100 ids per request, by id or by batch.

**HeyGen Studio Template API**

Added - July 2026

**Discover Studio templates and generate videos from them over the API**

You can now drive [HeyGen Studio](https://app.heygen.com/avatar/studio) templates programmatically — list them, read each one's variable schema, and render a video by filling the variables.

* New guide: [HeyGen Studio Template](https://heygen-1fa696a7.mintlify.site/templates.md) under Video Composition.
* **List & inspect:** [`GET /v3/templates`](https://heygen-1fa696a7.mintlify.site/reference/list-templates) and [`GET /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-template) return each template's variable schema (text, image, video, audio, character, voice) and scenes.
* **Generate:** [`POST /v3/templates/{template_id}`](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template) renders a video from your variable values, with options for `scene_ids`, `dimension`, `fps`, captions/subtitles, sharing, and webhooks.

**Batch Video Creation**

Added - July 2026

**Submit up to 100 videos in a single request**

Queue many videos at once instead of calling [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) per video.

* New guide: [Videos](https://heygen-1fa696a7.mintlify.site/batch-videos.md) under Batches.
* **Create:** [`POST /v3/videos/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-batch) accepts up to 100 payloads — each identical in shape to `POST /v3/videos` (`avatar`, `image`, or `cinematic_avatar`) — and returns a single `batch_id`.
* **Track:** [`GET /v3/videos/batches/{batch_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video-batch) returns aggregate status and per-item `video_id`s; a `callback_url` fires once when the whole batch finishes.

**Upload a Consent Video via API**

Added - July 2026

**Submit a pre-recorded consent video for a digital twin**

[`POST /v3/avatars/{group_id}/consent`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-consent) now accepts an optional `consent_video` field (as a `url`, `asset_id`, or `base64` asset). When supplied, the video is submitted directly for review — the avatar subject skips the hosted webcam page, and the response contains the avatar group without a consent `url`.

* Available to Enterprise API accounts with your account whitelisted — please [reach out to sales](https://www.heygen.com/contact-us/sales) or your account team to request access. The same applies to skipping the consent flow entirely.
* The webcam flow is unchanged and remains the default — see [Avatar Consent](https://heygen-1fa696a7.mintlify.site/docs/avatar-consent.md) for the full breakdown of consent levels.

**Hyperframes + HeyGen**

Added - July 2026

**Compose your avatar videos into finished, produced videos**

You can now combine a HeyGen avatar video with background music, sound effects, and Hyperframes graphics into a single composed render — Hyperframes acts as the compositor that lays an avatar clip into a designed scene, scores it, and renders it to one MP4.

* New guide: [Hyperframes + HeyGen](https://heygen-1fa696a7.mintlify.site/hyperframes-heygen.md) — an end-to-end pipeline wiring [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video), [`GET /v3/audio/sounds`](https://heygen-1fa696a7.mintlify.site/background-music) (music and sound effects), and [`POST /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/hyperframes) together.
* New page: [Introduction to Hyperframes](https://heygen-1fa696a7.mintlify.site/hyperframes-overview.md) — what the framework is, its core concepts, and the ways to render.
* Pass the avatar `video_url` and audio `audio_url`s into the render as `variables`, so one composition bundle produces many finished videos.

**Avatar III Engine Support**

Added - June 2026

**Support for the Avatar III engine**

We have expanded the capabilities of `POST /v3/videos` to include support for the Avatar III engine.

* **`POST /v3/videos`:**
  * Added support for the `avatar_iii` engine configuration.
  * Updated the `engine` property to include `AvatarIIIEngineConfig` in the `oneOf` schema definition, allowing for more flexible engine selection during video creation.

**New Endpoints & Features**

Added - June 2026

**Expanded API functionality and improved asset management**

We have introduced several new endpoints and configuration options to enhance your workflow:

* **Avatar & Video Configuration**:
  * `POST /v3/avatars`: Added `avatar_id` as an optional property for more granular prompt-based avatar creation.
  * `POST /v3/videos`: Added `reference_look_id` support within the `AvatarVEngineConfig` to refine video generation.

**Video Translation Improvements**

Changed - June 2026

**Clarified Stock Voice configuration for Video Translation**

Updated `POST /v2/video_translate` and `POST /v3/video-translations` to better reflect Enterprise capabilities.

* The `stock_voice_config` documentation has been updated to clarify that this feature uses preset HeyGen voices instead of cloning the original speaker's voice.
* `preferred_stock_voice_ids` is now explicitly defined as an optional pinning mechanism for stock voices.
* Note: Stock voice usage is an Enterprise feature gated by account permissions; please contact your HeyGen account team for access.

**Prompt Avatar Visual Reference**

Changed - June 2026

**`avatar_id` is now the visual reference for prompt avatars**

[`POST /v3/avatars`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar) with `type: "prompt"` now accepts an optional `avatar_id` — an existing look used as the visual reference for the generation. `avatar_group_id` no longer drives the reference image.

* Added `avatar_id` (optional): the look whose image conditions the generation. The new look is saved to the referenced avatar's group; if `avatar_group_id` is also provided, the avatar must belong to that group and the result is saved there. Returns 404 `AVATAR_NOT_FOUND` if the avatar doesn't exist, 400 `INVALID_PARAMETER` if it has no usable image or doesn't belong to the given group.
* Changed `avatar_group_id`: now only selects the group the generated avatar is saved to. It no longer conditions the generation on one of the group's looks.
* Changed `reference_images`: no longer requires `avatar_group_id` — it can be used on its own.
* **Migration Note:** if you passed `avatar_group_id` to keep a character's identity consistent across prompt-generated looks, pass the base look's ID as `avatar_id` instead. Requests with only `avatar_group_id` still succeed, but generate purely from the prompt.
* `type: "digital_twin"` and `type: "photo"` are unchanged.

See [Prompt to Avatar](https://heygen-1fa696a7.mintlify.site/docs/avatar-from-prompt.md) for the full behavior matrix.

**Sound Effects Support**

Added - June 2026

**Expanded Audio Search with Sound Effects**

The audio search functionality has been updated to include support for sound effects, allowing for more versatile audio retrieval beyond just background music.

* Updated `GET /v3/audio/sounds` to include `sound_effects` as a searchable type.
* The `type` query parameter now supports `sound_effects` in addition to the default `music`.
* API responses for `GET /v3/audio/sounds` will now include items with the `sound_effects` type.
* **Migration Note:** Clients that strictly validate the `type` field in the response against an enum list may need to update their schema definitions to include the new `sound_effects` value to prevent parsing errors.

**Credit Usage Tracking**

Added - June 2026

**Expanded usage insights for user accounts**

We have updated the user profile endpoints to provide better visibility into your account's credit consumption. You can now track your allocation and remaining balance directly through the API.

* Added `included_credits` and `remaining_credits` fields to the response objects for:
  * `GET /v1/user/me`
  * `GET /v3/users/me`

**Motion Prompt Enhancements**

Changed - June 2026

**Updated motion prompt capabilities for video generation**

The `motion_prompt` parameter for video generation now supports additional configurations for hand gestures and broader engine compatibility.

* Updated `motion_prompt` in `POST /v3/videos`:
  * Now supports natural-language control for both body motion and hand gestures.
  * Expanded support for photo avatars across both engines.
  * Added support for video avatars specifically when using `engine.type: 'avatar_v'`.

**New Video Type: Cinematic Avatar**

Added - June 2026

**Generate cinematic avatar video from a single prompt**

[`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) now supports **Cinematic Avatar** — a prompt-driven video type that composes scene, motion, and framing from a natural-language prompt plus one to three avatar looks (with optional reference media). No script or voice required.

* Added the `CreateVideoFromCinematicAvatar` schema to `POST /v3/videos` via an additive request discriminator (`cinematic_avatar`). Existing `CreateVideoFromAvatar` and `CreateVideoFromImage` requests are unaffected — this is a **non-breaking** change.
* Billed per video, not by duration. Choose any length from **4 to 15 seconds** via the `duration` parameter.
* Supports **720p** and **1080p** output.

No migration required. See the [Cinematic Avatar guide](https://heygen-1fa696a7.mintlify.site/avatar-shots.md) for the full parameter list.

**New Asset and Audio Endpoints**

Added - June 2026

**Expansion of Asset Management and Audio capabilities**

We have introduced new endpoints to streamline asset handling and provide better access to audio resources.

* `POST /v3/assets/direct-uploads`: Initialize a direct upload process for your custom assets.
* `POST /v3/assets/{asset_id}/complete`: Finalize the upload process for a specific asset.
* `GET /v3/audio/sounds`: Retrieve a list of available audio sounds for your projects.

**HyperFrames Resolution Constraints**

Changed - June 2026

**HyperFrames render resolution is now strictly typed**

We have updated the `POST /v3/hyperframes/renders` endpoint to enforce strict resolution settings.

* **Breaking Change:** The `resolution` property in `POST /v3/hyperframes/renders` is now strictly typed as a string enum (`1080p`, `4k`). Null values are no longer accepted.
* The `resolution` property now defaults to `1080p`.
* Added optional `aspect_ratio` support for `POST /v3/hyperframes/renders` and response schemas for `GET /v3/hyperframes/renders` and `GET /v3/hyperframes/renders/{render_id}`.

**Migration Steps:**
Ensure that any hardcoded `resolution` values sent to `POST /v3/hyperframes/renders` match the new `1080p` or `4k` enum strings. If you were previously sending `null` to indicate a default, you can now safely omit the property.

**HyperFrames Render API — Decomposed Resolution + Aspect Ratio**

Changed - May 31, 2026

**Breaking change: `resolution` is now a tier; `aspect_ratio` is a separate field**

`POST /v3/hyperframes/renders` previously took a single `resolution` value that conflated aspect ratio and resolution tier into one of six presets (`landscape`, `landscape-4k`, `portrait`, `portrait-4k`, `square`, `square-4k`). The same flat shape lived on `GET /v3/hyperframes/renders/{render_id}`.

Effective immediately, both endpoints decompose that single field into two:

* `resolution` ∈ `1080p` | `4k` — output resolution tier. Defaults to `1080p`.
* `aspect_ratio` ∈ `16:9` | `9:16` | `1:1` — output aspect ratio. Defaults to `16:9` (landscape). `9:16` is portrait; `1:1` is square.

The new shape matches the existing `/v3/videos` endpoint's `resolution` + `aspect_ratio` fields.

**Migration table**

Map each legacy preset to the new pair:

| OLD `resolution` | NEW |
| - | - |
| `landscape` | `{ "resolution": "1080p", "aspect_ratio": "16:9" }` |
| `landscape-4k` | `{ "resolution": "4k",    "aspect_ratio": "16:9" }` |
| `portrait` | `{ "resolution": "1080p", "aspect_ratio": "9:16" }` |
| `portrait-4k` | `{ "resolution": "4k",    "aspect_ratio": "9:16" }` |
| `square` | `{ "resolution": "1080p", "aspect_ratio": "1:1"  }` |
| `square-4k` | `{ "resolution": "4k",    "aspect_ratio": "1:1"  }` |

Requests using the legacy preset strings now return a 422 validation error — only the field shape moves.

**Not yet supported in this enum surface**: `720p`, `4:5`, `5:4`, and `auto`. These will follow in a separate update once the render pipeline supports the additional values.

**CLI**

`npx hyperframes cloud render` is updated in lockstep: the `--resolution` flag now accepts `1080p` | `4k`, and a new `--aspect-ratio` flag accepts `16:9` | `9:16` | `1:1`. Legacy values are rejected at the CLI layer with the same migration mapping.

**Brand Glossaries and Video Translation Enhancements**

Added - May 2026

**Introducing Brand Glossaries for Video Translation**

We have introduced Brand Glossaries to help maintain consistency in your video translations. You can now define custom term mappings to ensure specific terminology is translated accurately according to your brand guidelines.

* Added `GET /v3/brand-glossaries` to list and discover your available brand glossaries.
* Added `brand_glossary_id` as an optional request parameter to `POST /v2/video_translate` and `POST /v3/video-translations/proofreads`.
* The `brand_voice_id` parameter in these endpoints now acts as a legacy alias for `brand_glossary_id`, ensuring backward compatibility for your existing integrations.

**API Documentation and Default Parameter Updates**

Changed - May 2026

**Refined API documentation and aspect ratio defaults**

We have updated our API documentation across various endpoints to provide clearer guidance on usage and functionality. Additionally, we have updated the default behavior for aspect ratio selection.

* Updated `POST /v2/videos` and `POST /v3/videos` to clarify that the `aspect_ratio` defaults to `'16:9'` if not specified.
* Documentation descriptions for endpoints across Avatars, Lipsync, Video Agents, and Webhooks have been streamlined for improved clarity.
* Updated API tags for `GET /v3/brand-kits`, moving them under the `Brand` category.

**New Aspect Ratios for Social Formats**

Added - May 25, 2026

**Generate videos in square, portrait, landscape, and source-matched ratios**

`POST /v2/videos` and [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) now accept four additional values for `aspect_ratio`:

* `1:1` — square, great for feed posts
* `4:5` — portrait, optimized for Instagram and LinkedIn feeds
* `5:4` — landscape variant for feed placements
* `auto` — detects the source's dimensions (avatar footage or uploaded image) and preserves the original ratio, falling back to `16:9` when the source can't be read

Combine these with the existing `16:9` and `9:16` options to target multiple placements from a single integration.

**New Endpoint: Get Asset**

Added - May 25, 2026

**Retrieve metadata for an individual asset**

[`GET /v3/assets/{asset_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-asset) returns metadata for an asset in your workspace — including owner, upload timestamp, file type, and a publicly accessible URL. Use it to look up uploads on demand instead of paginating through the full asset list.

**Optional `consent_text` on Avatar Consent**

Changed - May 25, 2026

**Record the exact consent language presented to the avatar subject**

[`POST /v3/avatars/{group_id}/consent`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-consent) now accepts an optional `consent_text` field. Pass the wording the subject agreed to so you have a clear audit trail alongside the recorded consent. The field is optional — existing integrations continue to work unchanged.

**New `download_failed` Error Code**

Added - May 18, 2026

**Clearer signal when a user-supplied URL can't be fetched**

Requests that include a URL for video, image, audio, or any other resource can now return a dedicated `download_failed` error (HTTP `400`) when the URL can't be downloaded. The `message` field tells you which URL failed and why.

Common causes:

* URL isn't publicly accessible (auth required, private video, restricted sharing).
* URL is malformed or points to a page rather than a direct file.
* Remote server refused the connection or returned an error.
* Google Drive links must be shared with **Anyone with the link**.
* YouTube/Vimeo videos must be **public** — unlisted or private videos aren't supported.

The `resource_limit_exceeded` error message also now covers instant-avatar redo attempts and verified avatar group slots, with guidance to wait for limits to reset where applicable.

See the [error codes reference](https://heygen-1fa696a7.mintlify.site/docs/error-codes.md) for the full list.

**API Updates**

Added - May 2026

**Added Idempotency support and expanded API capabilities**

We have introduced support for the `Idempotency-Key` header across key endpoints to ensure safe retries for POST requests. Additionally, several endpoints now return a `409 Conflict` status to handle concurrent requests or state conflicts.

* **Idempotency-Key Support:** Added to `POST /v3/assets`, `POST /v3/avatars`, `POST /v3/avatars/{group_id}/consent`, `POST /v3/lipsyncs`, `POST /v3/video-translations`, `POST /v3/video-translations/proofreads`, `POST /v3/video-translations/proofreads/{proofread_id}/generate`, `POST /v3/videos`, `POST /v3/webhooks/endpoints`, and `POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret`.
* **New Endpoints:** Added `DELETE /v3/assets/{asset_id}`, `DELETE /v3/avatars/looks/{look_id}`, and `DELETE /v3/avatars/{group_id}`.
* **Default Values:** The `aspect_ratio` parameter now defaults to `16:9` in `POST /v2/videos` and `POST /v3/videos`.

**Video Translation Improvements**

Changed - May 2026

**Strict schema validation for frame rate modes**

The `fps_mode` property in `POST /v3/video-translations` has been updated to use a strict enum, ensuring more predictable behavior for video output.

* **Breaking Change:** The `fps_mode` property is now restricted to an enum. Supported values are now explicitly defined as `vfr`, `cfr`, and `passthrough`.
* **Migration:** Ensure your integration passes one of these three strings. Previously provided custom values may now be rejected.

**Corrected `avatar_video.success` Webhook Payload Fields**

Fixed - May 11, 2026

**Webhook payload field names now match what's actually delivered**

The documented payload for the `avatar_video.success` webhook event has been corrected. If you wired up handlers from the previous documentation, double-check the field names you're reading — the live payload uses these keys:

* `video_id`, `url`, `gif_download_url`, `video_page_url`, `video_share_page_url`, `folder_id`, `callback_id`

No change to the webhook delivery itself — this aligns the [webhook events reference](https://heygen-1fa696a7.mintlify.site/docs/webhook-events.md) with the payload the API has been sending.

**Video Engine Updates & Brand Kit Support**

Changed - May 2026

**Video engine updates and new brand kit integration**

We have updated the video generation workflow and introduced support for Brand Kits across Video Agents. Note that the `engine` parameter structure for `POST /v3/videos` has changed, which is a breaking change for existing integrations.

* **Breaking Change:** The `engine` property in `POST /v3/videos` now requires an object structure (e.g., `{"type": "avatar_v"}`) instead of a string. `ApiAvatarEngine` has been removed.
* **Video Scaling:** Added a new optional `fit` parameter to `POST /v3/videos` for both `CreateVideoFromAvatar` and `CreateVideoFromImage` request types.
* **Brand Kits:** Added `brand_kit_id` as an optional parameter to `POST /v3/video-agents` and `POST /v3/video-agents/{session_id}`.
* **New Endpoint:** Added `GET /v3/brand-kits` to retrieve available brand kit resources.
* **Parameter Constraints:** Note that `expressiveness` and `motion_prompt` in `POST /v3/videos` are now strictly for Avatar IV and are not supported when `engine.type` is set to `avatar_v`.

**Support for Stock TTS and Engine Selection**

Added - May 2026

**New configuration options for Video Translation and Video Generation**

We have introduced support for Stock TTS in video translations and added explicit engine selection for avatar-based video generation.

* **Video Translation:** Added `stock_voice_config` to `POST /v2/video_translate` and `POST /v3/video-translations`. This allows users to opt into Stock TTS instead of using Voice Cloning.
* **Video Generation:** Added an optional `engine` field to `POST /v3/videos` (for `CreateVideoFromAvatar` requests). You can now explicitly select between Avatar IV and Avatar V engines. If omitted, the system defaults to Avatar IV.

**Avatar Engine Metadata Updates**

Changed - May 2026

**Updated schema definitions for Avatar engine support**

Metadata for supported API engines has been updated across the avatar look endpoints to ensure consistency when retrieving avatar configurations.

* Updated `supported_api_engines` fields in:
  * `POST /v3/avatars`
  * `GET /v3/avatars/looks`
  * `GET /v3/avatars/looks/{look_id}`
  * `PATCH /v3/avatars/looks/{look_id}`

**Custom Watermark Controls**

Added - April 30, 2026

**Fine-tune watermark size, transparency, and position**

The `watermark` object on `POST /v3/videos` now accepts three new optional fields for finer control over how your watermark renders:

* `scale` (number, `0`–`2`, default `1.0`) — adjust the watermark size relative to its native resolution.
* `opacity` (number, `0`–`1`, default `1.0`) — control transparency.
* `placement` — choose an anchor corner (`top_left`, `top_right`, `bottom_left`, `bottom_right`) and apply fractional `offset_x` / `offset_y` values for precise positioning.

All fields are optional and backward-compatible. Omitting them preserves the existing bottom-right default behavior.

**Burned-in Captions**

Added - April 27, 2026

**Render captions directly into your videos**

`POST /v2/videos` and `POST /v3/videos` now accept a `caption.style` field. Set it to burn captions into the rendered video instead of (or in addition to) consuming the sidecar subtitle file at `subtitle_url`.

Useful for social platforms where viewers watch with sound off and you want captions baked into the asset.

**Custom Watermarks**

Added - April 27, 2026

**Apply your own watermark to generated videos**

`POST /v3/videos` accepts a new optional `watermark` property on both `CreateVideoFromAvatar` and `CreateVideoFromImage` requests. Pass a PNG or JPEG image to overlay it onto the rendered output — handy for branding, attribution, or moderation marks.

Available as a premium option for select Enterprise customers — [contact support](https://help.heygen.com) to request access.

**Watermark Schema Refactor**

Changed - April 27, 2026

**`watermark` now uses the `WatermarkInput` schema**

The inline schema previously used for the `watermark` field on video generation requests has been replaced with the dedicated `WatermarkInput` type. The shape of the property has changed — update existing payloads to match the new schema before upgrading.

**Video Title Search Requires a Value**

Changed - April 27, 2026

**Empty `title` queries are no longer accepted**

`GET /v2/videos` and `GET /v3/videos` now require at least one character for the `title` query parameter (`minLength` increased from 0 to 1). Omit the parameter entirely if you don't want to filter by title — sending an empty string will return a validation error.

**MCP Server Updates**

Added - April 2026

**Expanded tool coverage for the HeyGen MCP server**

The HeyGen Remote MCP server now includes tools for managing avatars, videos, lipsync, and video translation — making more of the API accessible to AI agents like Claude, Cursor, Gemini CLI, and Manus.

* Added avatar management tools: `create_digital_twin`, `create_photo_avatar`, `create_prompt_avatar`, `create_avatar_consent`, `list_avatar_looks`, `get_avatar_look`, `update_avatar_look`, and more.
* Added full video CRUD: `create_video_from_avatar`, `create_video_from_image`, `list_videos`, `get_video`, `delete_video`.
* Added lipsync and video translation management tools.
* See the [MCP overview](https://heygen-1fa696a7.mintlify.site/mcp/overview.md) for the full tool list.

**HeyGen CLI v0.0.4**

Added - April 2026

**CLI command surface synced with v3 API**

The HeyGen CLI now covers all v3 endpoints, including Video Agent, Lipsync, Video Translation (with Proofreads), Webhooks, and Assets.

* Added `--wait` flag for blocking until async operations complete, with configurable `--timeout`.
* Added `--request-schema` and `--response-schema` flags to inspect API schemas without authentication.
* Added `--force` flag for non-interactive destructive operations in CI.
* See the [CLI commands](https://heygen-1fa696a7.mintlify.site/commands.md) and [features](https://heygen-1fa696a7.mintlify.site/features.md) pages for usage details.

**v1/v2 API Deprecation Timeline**

Changed - April 2026

**v1 and v2 endpoints sunset on October 31, 2026**

A formal deprecation timeline is now in place for the v1 and v2 API. Both versions remain fully operational through October 31, 2026, after which they will be retired.

* Studio API (multi-scene) and Template API will continue to be supported on v2 until a v3 equivalent is available.
* See the [endpoint version comparison](https://heygen-1fa696a7.mintlify.site/endpoint-version-comparison.md) for a full migration checklist and feature comparison.

**New API Error Codes**

Added - April 2026

**More granular error responses across the API**

New error codes provide clearer feedback when requests fail, making it easier to handle edge cases in your integration.

* `ai_vendor_access_restricted` — workspace AI vendor policy blocks the request.
* `unlimited_mode_disabled` — avatar doesn't support unlimited mode.
* `voice_unavailable` — cloned voice failed processing or expired.
* `ephemeral_upload_disabled` — eager upload temporarily disabled for the account.
* `gateway_timeout` — external resource could not be fetched in time.
* See the full [error codes reference](https://heygen-1fa696a7.mintlify.site/docs/error-codes.md) for details and troubleshooting.

**Asset ID Documentation Update**

Changed - April 2026

**Standardized Asset ID descriptions**

Documentation across multiple endpoints has been clarified to consistently refer to asset IDs originating from the HeyGen asset upload endpoint. No functional changes were made to the API behavior.

* Applies to request bodies for:
  * `POST /v3/avatars`
  * `POST /v3/lipsyncs`
  * `POST /v3/video-agents` and `POST /v3/video-agents/{session_id}`
  * `POST /v3/video-translations`, `POST /v3/video-translations/proofreads`, and `PUT /v3/video-translations/proofreads/{proofread_id}/srt`
  * `POST /v3/videos`

**New Video Agents Endpoint**

Added - April 2026

**New endpoint for listing Video Agents**

We have introduced a new endpoint to allow developers to retrieve a list of all existing video agents associated with their account.

* Added `GET /v3/video-agents`: Use this endpoint to fetch your video agents, enabling easier integration and management of your agent instances.

**Avatar Error Code Update**

Changed - April 2026

**Updated error codes for Avatar endpoints**

We have updated the error response codes for avatar-related endpoints to provide more specific feedback when a group cannot be located.

* `GET /v3/avatars/{group_id}`: The 404 response error code has been updated from `not_found` to `avatar_group_not_found`.
* `POST /v3/avatars/{group_id}/consent`: The 404 response error code has been updated from `not_found` to `avatar_group_not_found`.

**Enhanced Video Generation Controls**

Added - April 2026

**Advanced voice customization and output formatting**

We have introduced new parameters to provide finer control over generated audio and video output quality.

* Added `volume` and `engine_settings` to `voice_settings` for `POST /v2/videos` and `POST /v3/videos`. These settings apply when using text-to-speech (`script` + `voice_id`).
* Added `output_format` to `POST /v3/videos` for both `CreateVideoFromAvatar` and `CreateVideoFromImage` request schemas.

**Webhook API Updates**

Added - April 2026

**Improved error handling for webhook management**

We have updated our webhook endpoints to provide more consistent and descriptive error responses.

* Added a `409` conflict response to `POST /v3/webhooks/endpoints` to better handle registration errors.
* Standardized error codes for `404` responses across `DELETE`, `PATCH`, and `POST /v3/webhooks/endpoints/{endpoint_id}/rotate-secret` by updating the error code to `webhook_not_found`.

**New Output Format Support**

Added - April 2026

**Support for custom output formats in video generation**

You can now specify a preferred output format when creating videos. The API response now includes the `output_format` field to confirm the format used for your generated video.

* Added optional `output_format` request property to `POST /v2/videos`.
* Added `output_format` to the response body of `POST /v2/videos` (200 OK).
* Added `output_format` to the response body of `POST /v3/videos` (200 OK).

**API Documentation Overhaul**

Changed - April 2026

**Comprehensive API Documentation Updates**

We have updated the endpoint descriptions across our entire V3 API to provide clearer guidance, better parameter context, and more precise functionality definitions. While the underlying API logic remains consistent, the improved documentation clarifies how to integrate with our latest engine versions and features.

* **Video Generation**: `POST /v3/videos` now officially documents support for the Avatar IV engine and upcoming Avatar V.
* **Avatars**: Clarified workflows for `POST /v3/avatars` (asynchronous training) and added guidance on the mandatory consent flow for private avatars via `POST /v3/avatars/{group_id}/consent`.
* **Video Agent**: Streamlined descriptions for session-based interactions, clearly distinguishing between `generate` (one-shot) and `chat` (multi-turn) modes.
* **Lipsync & Translation**: Updated documentation for `POST /v3/lipsyncs` and `POST /v3/video-translations` to emphasize the `speed` vs. `precision` mode selection for output quality.
* **Webhooks**: Clarified that `PATCH /v3/webhooks/endpoints/{endpoint_id}` performs a full replacement of the event types array.
* **Assets**: Updated supported MIME types for `POST /v3/assets` to include refined file type lists.

**Caption URL Support**

Added - April 2026

**Added caption\_url to Lipsync and Video Translation responses**

You can now retrieve the `caption_url` for generated lipsyncs and video translations, providing direct access to the generated caption files.

* `GET /v3/lipsyncs` and `GET /v3/lipsyncs/{lipsync_id}`
* `PATCH /v3/lipsyncs/{lipsync_id}`
* `GET /v3/video-translations` and `GET /v3/video-translations/{video_translation_id}`
* `PATCH /v3/video-translations/{video_translation_id}`

**Consent Flow Clarification**

Changed - April 2026

**Updated documentation for avatar consent**

Clarified the implementation details for the avatar consent flow to ensure a smoother user experience.

* `POST /v3/avatars/{group_id}/consent`: Updated documentation to clarify that the returned URL must be presented directly to the user in a browser to complete the consent process.

**Default Avatar Voices**

Changed - April 2026

**Support for avatar-default voices**

You can now generate videos using an avatar's default voice without explicitly specifying a `voice_id`. When creating a video, if `voice_id` is omitted while `avatar_id` is present, the system will automatically use the avatar's default voice.

* Updated `POST /v3/videos`: The `voice_id` requirement has been relaxed for both `CreateVideoFromAvatar` and `CreateVideoFromImage` schemas, allowing the system to fall back to the avatar's default voice.

**Video Agent Interaction Updates**

Changed - April 2026

**Enhanced capabilities for Video Agent interactions**

We have updated the description and scope of the `POST /v3/video-agents/{session_id}` endpoint to better reflect its versatility in managing agent-led workflows.

* Updated the endpoint description to clarify support for answering agent-posed questions and requesting specific edits or revisions.
* The request body schema has been updated to better align with these extended conversational and editing capabilities.

**Video Agent Status Update**

Added - April 2026

**New 'thinking' status for Video Agents**

We have introduced a new `thinking` state to the Video Agent response object to provide better visibility into agent processing workflows.

* Updated `POST /v3/video-agents`
* The `status` field in the response now includes the `thinking` enum value.
* Integration note: Ensure your client-side parsers are prepared to handle this new status value in the response body.

**Video Agent Enhancements**

Changed - April 2026

**Updated Video Agent session retrieval and new video listing**

We have refactored how resource data is handled in Video Agent sessions to improve performance. Additionally, we have introduced a new endpoint to fetch videos associated with a session.

* **Breaking Change:** The `resources` property has been removed from the response body of `GET /v3/video-agents/{session_id}`.
* **Migration:** To access resource details previously found in the session object, please use the new `GET /v3/video-agents/{session_id}/resources/{resource_id}` endpoint.
* **New Endpoint:** Added `GET /v3/video-agents/{session_id}/videos` to retrieve a list of videos generated within a specific agent session.

**Video Agent Session Refactor**

Changed - April 2026

**Breaking change: Restructured Video Agent session management**

We have updated the Video Agent API to simplify session handling. Please note that the previous `/v3/video-agents/sessions` path structure is deprecated and removed.

* **Removed endpoints:** `POST /v3/video-agents/sessions`, `GET /v3/video-agents/sessions/{session_id}`, `POST /v3/video-agents/sessions/{session_id}/messages`, `GET /v3/video-agents/sessions/{session_id}/resources`, and `POST /v3/video-agents/sessions/{session_id}/stop` have been removed.
* **Migration:** Replace existing calls with the new flattened endpoints under `/v3/video-agents/{session_id}`.
* **New endpoints added:**
  * `GET /v3/video-agents/{session_id}`
  * `POST /v3/video-agents/{session_id}`
  * `GET /v3/video-agents/{session_id}/resources/{resource_id}`
  * `POST /v3/video-agents/{session_id}/stop`

**Video Agent Enhancements**

Added - April 2026

**New configuration options for Video Agent sessions**

The `POST /v3/video-agents` endpoint now supports advanced control over session flow.

* Added `mode`: Supports `generate` (default, one-shot) and `chat` (multi-turn, allows revisions and follow-ups).
* Added `auto_proceed`: Enables automated progression through storyboards.
* Added `skip_agentic_stop`: Provides granular control over agent stopping behavior.

**Platform Updates**

Changed - April 2026

**API Operation ID update**

The operation ID for `GET /v3/users/me` has been updated from `getUserMeV3` to `getCurrentUserV3` to maintain consistency across our SDKs.

**New Video Creation Schema**

Changed - April 2026

**Refactored POST /v3/videos request body**

We have updated the `POST /v3/videos` endpoint to use a discriminated union for improved type safety and flexibility. This change replaces the legacy flat request structure with dedicated schemas for creating videos from avatars versus images.

* **Breaking Change:** The request body structure has been completely overhauled. You must now specify a type discriminator: use `CreateVideoFromAvatar` for digital twins/avatars or `CreateVideoFromImage` for custom image animation.
* **Migration:** All properties previously passed at the top level of the request (e.g., `avatar_id`, `image_url`, `voice_id`, `script`) must now be nested within the appropriate schema based on the video source.
* The operation ID for this endpoint has been updated from `createAvatarVideoV3` to `createVideo`.

**Improved API Error Handling**

Changed - April 2026

**Enhanced error messaging across all endpoints**

We have updated the error response schemas and examples across the entire API suite. Developers can now expect more consistent and detailed error responses for common issues, including:

* Improved `400 Bad Request` messages with clearer parameter validation feedback.
* Standardized `401 Unauthorized` responses when API keys are missing or expired.
* Consistent `429 Rate Limited` responses that align with standard retry headers.
* Better descriptive error messages for resource-specific failures (e.g., `404 Not Found` for specific IDs).

These updates ensure that your integrations can better handle exceptions and debugging.

**New v3 API endpoints**

Added - April 2026

**HeyGen for Developers — New v3 API Surface**

We've launched a new set of v3 endpoints across the HeyGen API, bringing a consistent interface, cursor-based pagination, and a unified asset input model to all major resources.

What's new:

* All v3 endpoints share a standard error format, cursor-based pagination (`has_more` / `next_token`), and consistent authentication via `X-Api-Key` or OAuth bearer token.
* Asset inputs now use a type-discriminated union — pass files as `{ "type": "url", "url": "..." }`, `{ "type": "asset_id", "asset_id": "..." }`, or `{ "type": "base64", "media_type": "...", "data": "..." }` across all endpoints.
* New and updated endpoints include: Video Agent (`POST /v3/video-agents`), Videos (`POST /v3/videos`), Video Translations (`POST /v3/video-translations`), Overdub (`POST /v3/overdubs`), Avatars (`POST /v3/avatars`), Assets (`POST /v3/assets`), Webhooks (`/v3/webhooks/*`), and User (`GET /v3/users/me`).

The v1/v2 endpoints continue to work, but we recommend migrating to v3 for all new integrations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.