---
title: Architecture
url: https://docs.kaltura.com/docs/conversational-agents/avatar-videos/architecture
---

## Architecture

The VOD Avatar system has two layers:

| Layer | URL Pattern | Purpose |
|-------|------------|---------|
| Server-side API | `https://video-avatar.$REGION.ovp.kaltura.com/api/v1/` | Video project CRUD, AI composition, video generation, avatar management |
| Embeddable widget | `https://unisphere.$REGION.ovp.kaltura.com/v1/` | Browser-based studio UI (uses the server-side API internally) |

**Server-side API flow:**

1. **List avatar templates** — `avatarTemplate/list` returns the 36 available AI presenters  
2. **Create an avatar** — `avatar/upsert` configures a template with a background  
3. **Create a video project** — `video/add` creates a project with scenes and narration  
4. **Optionally compose with AI** — `video/compose` generates scenes from source content  
5. **Preview audio** — `video/previewAudio` lets you hear the TTS narration before generating  
6. **Generate the video** — `video/generate` starts rendering; poll `video/get` until status is `ready`  
7. **Retrieve the Kaltura entry** — The `entryId` field on the completed video links to the generated media entry  

**Video status lifecycle:**

```
draft ──→ composing ──→ composed ──→ generating ──→ ready
  │          │                          │
  │          ↓                          ↓
  │       compose-error            generate-error
  │          │                          │
  └──────────┘──── resetStatus ─────────┘
```

| Status | Meaning |
|--------|---------|
| `draft` | New project, scenes can be edited |
| `composing` | AI is generating scenes from source content (read-only) |
| `composed` | AI composition complete, scenes populated and editable |
| `compose-error` | AI composition failed — use `resetStatus` to return to `draft` |
| `generating` | Video is being rendered (read-only) |
| `ready` | Video generation complete, `entryId` populated with the Kaltura media entry |
| `generate-error` | Generation failed — use `resetStatus` to return to `composed` or `draft` |

Scenes are read-only while the video is in `composing` or `generating` status — edits are accepted again once the operation completes or is reset.