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.