## 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](/content/changelog/index.html) 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](/content/changelog/index.html) for replacements
- Test all migrated endpoints in staging before October 31, 2026.