> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/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.

<Update label="Prompt Avatar Visual Reference" tags={["Avatars", "Breaking Change"]} description="Changed - June 2026">
  **`avatar_id` is now the visual reference for prompt avatars**

  [`POST /v3/avatars`](/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 [Create Avatar](/docs/create-avatar#prompt-to-avatar) for the full behavior matrix.
</Update>

<Update label="Sound Effects Support" tags={["Assets", "Breaking Change"]} description="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.
</Update>

<Update label="Credit Usage Tracking" tags={["User", "Platform"]} description="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`
</Update>

<Update label="Motion Prompt Enhancements" tags={["Videos", "Avatars"]} description="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'`.
</Update>

<Update label="New Video Type: Cinematic Avatar" tags={["Videos"]} description="Added - June 2026">
  **Generate cinematic avatar video from a single prompt**

  [`POST /v3/videos`](/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 at a flat **\$7.00 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](/avatar-shots) for the full parameter list.
</Update>

<Update label="New Asset and Audio Endpoints" tags={["Assets", "Voices", "Platform"]} description="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.
</Update>

<Update label="HyperFrames Resolution Constraints" tags={["HyperFrames", "Breaking Change"]} description="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.
</Update>

<Update label="HyperFrames Render API — Decomposed Resolution + Aspect Ratio" tags={["HyperFrames", "Breaking Change"]} description="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`. 4K renders are billed at 1.5× the 1080p rate.
  * `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. Aspect ratio does not affect pricing.

  **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. Pricing for 4K renders is unchanged — 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.
</Update>

<Update label="Brand Glossaries and Video Translation Enhancements" tags={["Video Translation", "Assets"]} description="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.
</Update>

<Update label="API Documentation and Default Parameter Updates" tags={["Platform", "Videos"]} description="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.
</Update>

<Update label="New Aspect Ratios for Social Formats" tags={["Videos"]} description="Added - May 25, 2026">
  **Generate videos in square, portrait, landscape, and source-matched ratios**

  `POST /v2/videos` and [`POST /v3/videos`](/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.
</Update>

<Update label="New Endpoint: Get Asset" tags={["Assets"]} description="Added - May 25, 2026">
  **Retrieve metadata for an individual asset**

  [`GET /v3/assets/{asset_id}`](/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.
</Update>

<Update label="Optional `consent_text` on Avatar Consent" tags={["Avatars"]} description="Changed - May 25, 2026">
  **Record the exact consent language presented to the avatar subject**

  [`POST /v3/avatars/{group_id}/consent`](/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.
</Update>

<Update label="New `download_failed` Error Code" tags={["Errors"]} description="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](/docs/error-codes) for the full list.
</Update>

<Update label="Avatar V Pricing Parity with Avatar IV" tags={["Pricing"]} description="Changed - May 12, 2026">
  **Avatar V is billed at the same rates as Avatar IV**

  Per-second video generation rates for Avatar V now match Avatar IV across both [self-serve](/docs/pricing) and [enterprise](/docs/enterprise-pricing) plans. No action required — pricing tables have been updated to reflect the combined Avatar IV & V rates.
</Update>

<Update label="API Updates" tags={["Videos", "Assets", "Avatars", "Video Translation", "Lipsync", "Webhooks"]} description="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`.
</Update>

<Update label="Video Translation Improvements" tags={["Video Translation", "Breaking Change"]} description="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.
</Update>

<Update label="Corrected `avatar_video.success` Webhook Payload Fields" tags={["Webhooks","Videos"]} description="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](/docs/webhook-events) with the payload the API has been sending.
</Update>

<Update label="Video Engine Updates & Brand Kit Support" tags={["Videos", "Video Agent", "Breaking Change"]} description="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`.
</Update>

<Update label="Support for Stock TTS and Engine Selection" tags={["Video Translation", "Videos"]} description="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.
</Update>

<Update label="Avatar Engine Metadata Updates" tags={["Avatars"]} description="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}`
</Update>

<Update label="Custom Watermark Controls" tags={["Videos"]} description="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.
</Update>

<Update label="Voice Cloning API" tags={["Voices"]} description="Added - April 27, 2026">
  **Programmatic voice cloning is now available**

  You can now create and manage voice clones directly from the API, no dashboard step required.

  * `POST /v3/voices/clone` initiates a clone from a reference audio sample.
  * `GET /v3/voices/{voice_id}` returns clone status and details so you can poll until processing completes.
  * Use the resulting `voice_id` anywhere a voice is accepted (`POST /v3/videos`, `POST /v3/voices/speech`, etc.).

  See the [voices overview](/docs/voices/overview) for details.
</Update>

<Update label="Burned-in Captions" tags={["Videos"]} description="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.
</Update>

<Update label="Custom Watermarks" tags={["Videos"]} description="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.
</Update>

<Update label="Watermark Schema Refactor" tags={["Videos","Breaking Change"]} description="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.
</Update>

<Update label="Video Title Search Requires a Value" tags={["Videos","Breaking Change"]} description="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.
</Update>

<Update label="Clearer Voice Clone Quota Errors" tags={["Voices"]} description="Fixed - April 27, 2026">
  **Better error feedback when the voice clone limit is reached**

  `POST /v3/voices/clone` now returns the `resource_limit_reached` error code (HTTP 400) when your account has hit its voice clone quota, instead of a generic validation error. The response message tells you to delete unused clones or contact support to raise the limit. See the [error codes reference](/docs/error-codes#resource-limit-reached) for handling guidance.
</Update>

<Update label="MCP Server Updates" tags={["MCP","Platform"]} description="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.
  * Added `design_voice` for finding voices from a natural-language description.
  * See the [MCP overview](/mcp/overview) for the full tool list.
</Update>

<Update label="HeyGen CLI v0.0.4" tags={["CLI","Platform"]} description="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](/commands) and [features](/features) pages for usage details.
</Update>

<Update label="v1/v2 API Deprecation Timeline" tags={["Platform"]} description="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](/endpoint-version-comparison) for a full migration checklist and feature comparison.
</Update>

<Update label="New API Error Codes" tags={["Platform"]} description="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](/docs/error-codes) for details and troubleshooting.
</Update>

<Update label="Starfish Engine Integration" tags={["Voices","Platform"]} description="Changed - April 2026">
  **New requirement for Starfish engine compatibility**

  Text-to-speech generation endpoints now require the use of voices that support the Starfish engine.

  * Updated `POST /v1/audio/text_to_speech` and `POST /v3/voices/speech` documentation.
  * Developers should filter for compatible voices by passing `engine=starfish` when calling the voice listing endpoints.
</Update>

<Update label="Asset ID Documentation Update" tags={["Videos","Avatars","Video Translation","Lipsync","Video Agent"]} description="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`
</Update>

<Update label="New Video Agents Endpoint" tags={["Video Agent","Platform"]} description="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.
</Update>

<Update label="Avatar Error Code Update" tags={["Avatars"]} description="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`.
</Update>

<Update label="Enhanced Video Generation Controls" tags={["Videos","Voices"]} description="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.
</Update>

<Update label="Webhook API Updates" tags={["Webhooks"]} description="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`.
</Update>

<Update label="New Output Format Support" tags={["Videos"]} description="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).
</Update>

<Update label="API Documentation Overhaul" tags={["Platform","Videos","Avatars","Video Agent","Voices","Video Translation","Lipsync","Webhooks"]} description="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.
</Update>

<Update label="Caption URL Support" tags={["Lipsync","Video Translation"]} description="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}`
</Update>

<Update label="Consent Flow Clarification" tags={["Avatars"]} description="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.
</Update>

<Update label="Default Avatar Voices" tags={["Videos","Avatars"]} description="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.
</Update>

<Update label="Video Agent Interaction Updates" tags={["Video Agent"]} description="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.
</Update>

<Update label="Video Agent Status Update" tags={["Video Agent","Platform"]} description="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.
</Update>

<Update label="Video Agent Enhancements" tags={["Video Agent","Breaking Change"]} description="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.
</Update>

<Update label="Video Agent Session Refactor" tags={["Video Agent","Breaking Change"]} description="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`
</Update>

<Update label="Video Agent Enhancements" tags={["Video Agent"]} description="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.
</Update>

<Update label="Platform Updates" tags={["Platform","User"]} description="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.
</Update>

<Update label="New Voice Creation Endpoint" tags={["Voices"]} description="Added - April 2026">
  **Added support for custom voice creation**

  We have introduced a new endpoint to allow developers to programmatically create and add new voices to their HeyGen account.

  * Added `POST /v3/voices` to the API.
</Update>

<Update label="New Video Creation Schema" tags={["Videos","Breaking Change"]} description="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`.
</Update>

<Update label="Improved API Error Handling" tags={["Platform"]} description="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.
</Update>

<Update label="New v3 API endpoints" tags={["Platform"]} description="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`), Voices (`GET /v3/voices`, `POST /v3/voices/speech`), 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.
</Update>