Endpoint Version Comparison

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 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 for replacements
• Test all migrated endpoints in staging before October 31, 2026