Endpoint Version Comparison - HeyGen Documentation

Deprecation Timeline

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.

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:

{
  "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`
Video Agent	`POST /v1/video_agent/generate`	—	`POST /v3/video-agents`
Studio API (multi-scene)	—	`POST /v2/video/generate`	`POST /v3/videos` with `type: "studio"`
Template API (variables)	—	`POST /v2/template/{id}/generate`	`POST /v3/templates/{id}`
List and Get Templates	—	`GET /v2/templates`, `GET /v2/template/{id}`	`GET /v3/templates`, `GET /v3/templates/{id}`
Poll Video Status	`GET /v1/video_status.get`	`GET /v2/videos/{video_id}`	`GET /v3/videos/{video_id}`
List Videos	`GET /v1/video.list`	`GET /v2/videos`	`GET /v3/videos`
Delete a Video	`DELETE /v1/video.delete`	`DELETE /v2/videos/{video_id}`	`DELETE /v3/videos/{video_id}`
Video Translation	—	`POST /v2/video_translate`	`POST /v3/video-translations`
Translation Languages	—	`GET /v2/video_translate/target_languages`	`GET /v3/video-translations/languages`
Translation Captions	—	`GET /v2/video_translate/caption`	`srt_caption_url` and `vtt_caption_url` on `GET /v3/video-translations/{id}`
Proofread Workflow	—	`POST /v2/video_translate/proofread`	`POST /v3/video-translations/proofreads`
Text-to-Speech	`POST /v1/audio/text_to_speech`	—	`POST /v3/voices/speech`
List Voices	`GET /v1/voice.list`, `GET /v1/audio/voices`	`GET /v2/voices`	`GET /v3/voices`
Voice Clone	—	`POST /v2/voices/clone`	`POST /v3/voices/clone`
List Avatars	`GET /v1/avatar.list`	`GET /v2/avatars`, `GET /v2/avatar_group.list`	`GET /v3/avatars`
Photo Avatars	—	`POST /v2/photo_avatar/*`	`POST /v3/avatars` with `type: "photo"`
Webhook Management	`/v1/webhook/endpoint.*`	—	`/v3/webhooks/endpoints` with secret rotation and an event log
Asset Management	`GET /v1/asset/list`, `POST /v1/asset/{id}/delete`	—	`POST /v3/assets` and `DELETE /v3/assets/{asset_id}`
Folders	`POST /v1/folders/create`	—	`POST /v3/folders` and `GET /v3/folders/{folder_id}`
Brand Glossary	`GET /v1/brand_voice/list`	—	`GET /v3/brand-glossaries`
Account Info	`GET /v1/user/me`	`GET /v2/user/remaining_quota`	`GET /v3/users/me`
Batch Creation	—	—	`POST /v3/videos/batches`
Lipsync	—	—	`POST /v3/lipsyncs`
Voice Design	—	—	`POST /v3/voices`

On v3, avatar video generation selects a rendering engine per request, Avatar III, IV, or V, through the engine field. See Models.

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
Avatar Creation	`POST /v3/avatars`	One endpoint for footage, photo, and prompt. See Create Avatar
Look Packs	`POST /v3/avatars/looks`	Curated look sets for an avatar you own
Avatar Consent Flow	`POST /v3/avatars/{group_id}/consent`	Required before a digital twin renders
HyperFrames	`POST /v3/hyperframes/renders`	Render HTML, CSS and JS projects to video
Background Removal	`POST /v3/background-removals`	Managed background-removal jobs
Audio Search	`GET /v3/audio/sounds`	Background-music and sound-effects catalog
Batch Video Creation	`POST /v3/videos/batches`	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, including multi-scene calls, which become type: "studio"
Replace GET /v1/video_status.get with GET /v3/videos/{video_id}
Replace POST /v1/video_agent/generate with POST /v3/video-agents
Replace avatar and voice listing calls with GET /v3/avatars and GET /v3/voices
Replace POST /v1/audio/text_to_speech with POST /v3/voices/speech
Replace POST /v2/template/{id}/generate with POST /v3/templates/{id}
Replace POST /v2/video_translate with POST /v3/video-translations, 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
Move /v1/webhook/endpoint.* management to /v3/webhooks/endpoints
Update pagination logic to cursor-based where applicable
Test all migrated endpoints in staging before October 31, 2026

​Deprecation Timeline

​Find your own legacy calls

​Feature Comparison

​v3-Only Features (No Legacy Equivalent)

​v3 Platform Improvements

​Migration Checklist