Endpoint Version Comparison

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

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 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	✅ POST /v3/videos (type: "studio")
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.

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

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
• Template API: now available on v3 — migrate POST /v2/template/{id}/generate to POST /v3/templates/{id}
• Studio API: now available on v3 — migrate multi-scene POST /v2/video/generate calls to POST /v3/videos with type: "studio"
• Test all migrated endpoints in staging before October 31, 2026