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.

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`	✅ `POST /v3/templates/{id}`
Batch Video Creation	—	—	✅ `POST /v3/videos/batches`
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`

On v3, avatar video generation supports per-request rendering-engine selection — Avatar III, IV, or V — via the engine field. See Models.

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 Realtime	`POST /v3/avatar-realtime`	Low-latency streaming avatar sessions
HyperFrames	`POST /v3/hyperframes/renders`	Render HTML/CSS/JS projects to video
Background Removal	`/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
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

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.

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
Template API: now available on v3 — migrate POST /v2/template/{id}/generate to POST /v3/templates/{id}
Flag: Studio API (multi-scene) remains v2-only for now; monitor the v3 changelog for a replacement
Test all migrated endpoints in staging before October 31, 2026