Architecture - Avatar Videos

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:

List avatar templates — avatarTemplate/list returns the 36 available AI presenters
Create an avatar — avatar/upsert configures a template with a background
Create a video project — video/add creates a project with scenes and narration
Optionally compose with AI — video/compose generates scenes from source content
Preview audio — video/previewAudio lets you hear the TTS narration before generating
Generate the video — video/generate starts rendering; poll video/get until status is ready
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.

Architecture​

Architecture