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

# Endpoint Version Comparison

> Compare HeyGen API v1, v2, and v3 side-by-side. See which endpoints moved between versions, what's deprecated, and how to migrate existing integrations to v3.

## Deprecation Timeline

The v1 and v2 API endpoints are entering a planned sunset period. Both versions will continue to operate normally through **October 31, 2026**, giving teams ample runway to migrate at their own pace.

| Phase           | Window                                  | What to Expect                                                                                |
| --------------- | --------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Current**     | Now — October 31, 2026                  | v1/v2 endpoints remain fully operational. v3 is live and recommended for all new development. |
| **End of Life** | November 1, 2026 — end of support date. | v1/v2 endpoints will be retired. All traffic should be routed to v3 by this date.             |

> **Note:** If your integration relies on **Studio API (multi-scene)** or **Template API** features that are not yet available in v3, those v2 endpoints will continue to be supported until a v3 equivalent is in place. See the [v3 changelog](/changelog) for updates.

## Feature Comparison

| Feature                         | v1                                | v2                                     | v3                              |
| ------------------------------- | --------------------------------- | -------------------------------------- | ------------------------------- |
| **Avatar Video Generation**     | ✅ `POST /v1/video/generate`       | ✅ `POST /v2/video/generate`            | ✅ `POST /v3/videos`             |
| **Video Agent**                 | ✅ `POST /v1/video-agent/generate` | —                                      | ✅ `POST /v3/video-agents`       |
| **Studio API (multi-scene)**    | —                                 | ✅ `POST /v2/video/generate`            | ⏳ Not yet available             |
| **Template API (variables)**    | —                                 | ✅ `POST /v2/template/{id}/generate`    | ⏳ Not yet available             |
| **Video Translation**           | —                                 | ✅ `POST /v2/video_translate/translate` | ✅ `POST /v3/video-translations` |
| **Lipsync**                     | —                                 | —                                      | ✅ `POST /v3/lipsyncs`           |
| **Voice Design (prompt-based)** | —                                 | —                                      | ✅ `POST /v3/voices`             |
| **Text-to-Speech (Starfish)**   | —                                 | —                                      | ✅ `POST /v3/voices/speech`      |
| **Webhook Management**          | —                                 | callback\_url param only               | ✅ Full CRUD + secret rotation   |
| **Asset Upload**                | ✅ `POST /v1/video/upload`         | —                                      | ✅ `POST /v3/assets`             |
| **List Avatars**                | ✅ `GET /v1/avatar.list`           | ✅ `GET /v2/avatars`                    | ✅ `GET /v3/avatars`             |
| **List Voices**                 | ✅ `GET /v1/voice.list`            | ✅ `GET /v2/voices`                     | ✅ `GET /v3/voices`              |
| **Poll Video Status**           | ✅ `GET /v1/video_status.get`      | —                                      | ✅ `GET /v3/videos/{id}`         |
| **User / Account Info**         | ✅ `GET /v1/user/me`               | —                                      | ✅ `GET /v3/users/me`            |

## v3-Only Features (No Legacy Equivalent)

| Feature                   | Endpoint                              | Notes                                             |
| ------------------------- | ------------------------------------- | ------------------------------------------------- |
| Lipsync                   | `POST /v3/lipsyncs`                   | Speed and precision modes                         |
| Voice Design              | `POST /v3/voices`                     | Design a voice from a text prompt                 |
| Text-to-Speech (Starfish) | `POST /v3/voices/speech`              | New TTS engine                                    |
| Proofread Workflow        | `/v3/video-translations/proofreads/*` | SRT review/edit before final render               |
| Webhook Management        | `/v3/webhooks/endpoints/*`            | Full CRUD, secret rotation, event log             |
| Video Agent (full)        | `/v3/video-agents/*`                  | Styles, references, chat mode                     |
| Avatar Consent Flow       | `POST /v3/avatars/{group_id}/consent` | Required for custom avatar creation               |
| Cursor-based Pagination   | All v3 list endpoints                 | Standard across every resource                    |
| Unified Asset Input       | All v3 creation endpoints             | `url` / `asset_id` / `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 only  | Managed endpoints, event types, signed payloads           |
| Video request body | Flat object                | Discriminated union (`type: "avatar"` or `type: "image"`) |
| Voice fallback     | `voice_id` always required | Falls back to avatar's default voice when omitted.        |

## Migration Checklist

* Inventory all v1/v2 endpoint calls in your codebase
* Replace `POST /v1/video/generate` and `POST /v2/video/generate` with `POST /v3/videos`
* Replace `GET /v1/video_status.get` with `GET /v3/videos/{id}`
* Replace avatar and voice listing endpoints with v3 equivalents
* Replace `POST /v1/video/upload` with `POST /v3/assets`
* Replace `GET /v1/user/me` with `GET /v3/users/me`
* Migrate video translation calls to `/v3/video-translations`
* Update webhook handling from `callback_url` to managed `/v3/webhooks/endpoints`
* Update pagination logic to cursor-based where applicable
* **Flag:** If using Studio API (multi-scene) or Template API — these remain v2-only for now; monitor the [v3 changelog](/changelog) for replacements
* Test all migrated endpoints in staging before October 31, 2026