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

# Endpoint Version Comparison

> Compare HeyGen API v1, v2, and v3 endpoints and migrate existing integrations to v3.

## Deprecation Timeline

| Phase | Window | What to Expect |
| - | - | - |
| **Sunset** | October 31, 2026 | v1/v2 reached end of support. v3 is the supported API. |
| **Removal** | In progress | v1/v2 endpoints are being removed. Calls may fail intermittently until removal is complete. Route all traffic to v3. |

## Find your own legacy calls

Every v1 and v2 response tells you it is legacy and names its replacement, so you can inventory a codebase by running it rather than reading it. Responses carry `Deprecation: true` and a `Sunset` header of `Sat, 31 Oct 2026 00:00:00 GMT`, and the JSON body gains a `warning` object:

```json theme={null}
{
  "warning": {
    "message": "This v2 endpoint is Legacy and will be removed on 2026-10-31. Developers: migrate to POST /v3/videos. Documentation: https://developers.heygen.com/reference/create-video",
    "v3_endpoint": "POST /v3/videos",
    "docs_url": "https://developers.heygen.com/reference/create-video",
    "sunset_date": "2026-10-31"
  }
}
```

`v3_endpoint` is the exact operation to move to. Log it across a day of traffic and you have your migration list.

## Feature Comparison

| Feature | v1 | v2 | v3 |
| - | - | - | - |
| **Avatar Video Generation** | — | `POST /v2/video/generate` | [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) |
| **Video Agent** | `POST /v1/video_agent/generate` | — | [`POST /v3/video-agents`](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session) |
| **Studio API (multi-scene)** | — | `POST /v2/video/generate` | [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video) with `type: "studio"` |
| **Template API (variables)** | — | `POST /v2/template/{id}/generate` | [`POST /v3/templates/{id}`](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template) |
| **List and Get Templates** | — | `GET /v2/templates`, `GET /v2/template/{id}` | [`GET /v3/templates`](https://heygen-1fa696a7.mintlify.site/reference/list-templates), [`GET /v3/templates/{id}`](https://heygen-1fa696a7.mintlify.site/reference/get-template) |
| **Poll Video Status** | `GET /v1/video_status.get` | `GET /v2/videos/{video_id}` | [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video) |
| **List Videos** | `GET /v1/video.list` | `GET /v2/videos` | [`GET /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/list-videos) |
| **Delete a Video** | `DELETE /v1/video.delete` | `DELETE /v2/videos/{video_id}` | [`DELETE /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-video) |
| **Video Translation** | — | `POST /v2/video_translate` | [`POST /v3/video-translations`](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation) |
| **Translation Languages** | — | `GET /v2/video_translate/target_languages` | [`GET /v3/video-translations/languages`](https://heygen-1fa696a7.mintlify.site/reference/list-supported-translation-languages) |
| **Translation Captions** | — | `GET /v2/video_translate/caption` | `srt_caption_url` and `vtt_caption_url` on [`GET /v3/video-translations/{id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video-translation) |
| **Proofread Workflow** | — | `POST /v2/video_translate/proofread` | [`POST /v3/video-translations/proofreads`](https://heygen-1fa696a7.mintlify.site/reference/create-proofread-session) |
| **Text-to-Speech** | `POST /v1/audio/text_to_speech` | — | [`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech) |
| **List Voices** | `GET /v1/voice.list`, `GET /v1/audio/voices` | `GET /v2/voices` | [`GET /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices) |
| **Voice Clone** | — | `POST /v2/voices/clone` | [`POST /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/create-or-retrain-an-audio-voice) |
| **List Avatars** | `GET /v1/avatar.list` | `GET /v2/avatars`, `GET /v2/avatar_group.list` | [`GET /v3/avatars`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-groups) |
| **Photo Avatars** | — | `POST /v2/photo_avatar/*` | [`POST /v3/avatars`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar) with `type: "photo"` |
| **Webhook Management** | `/v1/webhook/endpoint.*` | — | [`/v3/webhooks/endpoints`](https://heygen-1fa696a7.mintlify.site/reference/list-webhook-endpoints) with secret rotation and an event log |
| **Asset Management** | `GET /v1/asset/list`, `POST /v1/asset/{id}/delete` | — | [`POST /v3/assets`](https://heygen-1fa696a7.mintlify.site/reference/upload-asset) and [`DELETE /v3/assets/{asset_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-asset) |
| **Folders** | `POST /v1/folders/create` | — | [`POST /v3/folders`](https://heygen-1fa696a7.mintlify.site/reference/create-folder) and [`GET /v3/folders/{folder_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-folder) |
| **Brand Glossary** | `GET /v1/brand_voice/list` | — | [`GET /v3/brand-glossaries`](https://heygen-1fa696a7.mintlify.site/reference/list-brand-glossaries) |
| **Account Info** | `GET /v1/user/me` | `GET /v2/user/remaining_quota` | [`GET /v3/users/me`](https://heygen-1fa696a7.mintlify.site/reference/get-current-user) |
| **Batch Creation** | — | — | [`POST /v3/videos/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-batch) |
| **Lipsync** | — | — | [`POST /v3/lipsyncs`](https://heygen-1fa696a7.mintlify.site/reference/create-lipsync) |

On v3, avatar video generation selects a rendering engine per request, Avatar III, IV, or V, through the `engine` field. See [Models](https://heygen-1fa696a7.mintlify.site/models).

## v3-Only Features (No Legacy Equivalent)

| Feature | Endpoint | Notes |
| - | - | - |
| Lipsync | [`POST /v3/lipsyncs`](https://heygen-1fa696a7.mintlify.site/reference/create-lipsync) | Speed and precision modes |
| Avatar Creation | [`POST /v3/avatars`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar) | One endpoint for footage, photo, and prompt. See [Create Avatar](https://heygen-1fa696a7.mintlify.site/docs/create-avatar.md) |
| Look Packs | [`POST /v3/avatars/looks`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-looks) | Curated look sets for an avatar you own |
| Avatar Consent Flow | [`POST /v3/avatars/{group_id}/consent`](https://heygen-1fa696a7.mintlify.site/reference/create-avatar-consent) | Required before a digital twin renders |
| HyperFrames | [`POST /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/reference/create-hyperframes-render) | Render HTML, CSS and JS projects to video |
| Background Removal | `POST /v3/background-removals` | Managed background-removal jobs |
| Audio Search | [`GET /v3/audio/sounds`](https://heygen-1fa696a7.mintlify.site/reference/search-audio-music-or-sound-effects) | Background-music and sound-effects catalog |
| Batch Video Creation | [`POST /v3/videos/batches`](https://heygen-1fa696a7.mintlify.site/reference/create-video-batch) | Submit up to 100 videos in one request |
| Cursor-based Pagination | All v3 list endpoints | Standard across every resource |
| Unified Asset Input | All v3 creation endpoints | `url`, `asset_id` or `base64` discriminated union |

## v3 Platform Improvements

| Capability | v1/v2 | v3 |
| - | - | - |
| Pagination | Offset-based or none | Cursor-based (all list endpoints) |
| Asset references | Varies by endpoint | Unified `url` / `asset_id` / `base64` union |
| Webhook delivery | `callback_url` param, plus v1 endpoint management | Managed endpoints, event types, signed payloads, secret rotation |
| Video request body | Flat object | Discriminated union (`type: "avatar"`, `"image"`, `"cinematic_avatar"` or `"studio"`) |
| Voice fallback | `voice_id` always required | Falls back to the avatar's default voice when omitted |

## Migration Checklist

* Inventory your v1/v2 calls by logging the `warning.v3_endpoint` field on legacy responses
* Replace `POST /v2/video/generate` with [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video), including multi-scene calls, which become `type: "studio"`
* Replace `GET /v1/video_status.get` with [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video)
* Replace `POST /v1/video_agent/generate` with [`POST /v3/video-agents`](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session)
* Replace avatar and voice listing calls with [`GET /v3/avatars`](https://heygen-1fa696a7.mintlify.site/reference/list-avatar-groups) and [`GET /v3/models/audio/voices`](https://heygen-1fa696a7.mintlify.site/reference/list-audio-voices)
* Replace `POST /v1/audio/text_to_speech` with [`POST /v3/models/audio/tts`](https://heygen-1fa696a7.mintlify.site/reference/generate-model-speech)
* Replace `POST /v2/template/{id}/generate` with [`POST /v3/templates/{id}`](https://heygen-1fa696a7.mintlify.site/reference/generate-video-from-template)
* Replace `POST /v2/video_translate` with [`POST /v3/video-translations`](https://heygen-1fa696a7.mintlify.site/reference/create-video-translation), and read captions from the detail response instead of `GET /v2/video_translate/caption`
* Replace `GET /v1/user/me` and `GET /v2/user/remaining_quota` with [`GET /v3/users/me`](https://heygen-1fa696a7.mintlify.site/reference/get-current-user)
* Move `/v1/webhook/endpoint.*` management to [`/v3/webhooks/endpoints`](https://heygen-1fa696a7.mintlify.site/reference/list-webhook-endpoints)
* Update pagination logic to cursor-based where applicable
* Test all migrated endpoints before moving production traffic


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