Skip to main content

Kaltura Avatar SDK & API

Welcome to the Kaltura Avatar documentation. Bring lifelike avatars to your web applications with real-time WebRTC streaming and flexible control options.

Architecture Overview​

The Kaltura Avatar system consists of two main components:

1. Client SDK (Required)​

The Client SDK is always required to display avatars in your application. It handles:

  • WebRTC video streaming
  • Video element creation and attachment
  • Connection management and keep-alive
  • Real-time avatar display

Package: @unisphere/models-sdk-js

Client SDK is Required

You cannot display avatars without the Client SDK. It must be included in every application that shows avatars.

2. Control Layer​

The control layer determines how you interact with the avatar (making it speak, interrupting, etc.). You have two options:

Option A: SDK-Based Control​

The SDK creates and controls the avatar session directly in the client. Kaltura Session is in your client code.

How:

// Pass Kaltura Session to SDK constructor
const session = new KalturaAvatarSession('your-kaltura-session');
await session.createSession({ avatarId: 'avatar-123' });
await session.sayText('Hello!'); // Control from client

Best for:

  • Prototypes and demos
  • Internal tools
  • Learning and testing
  • ⚠️ NOT recommended for production

Option B: API-Based Control (Recommended) ✅​

Your backend creates and controls the avatar session. Frontend only displays it. Kaltura Session stays secure on your server.

How:

// Backend creates session (has Kaltura Session)
const { sessionId, token } = await backend.createAvatarSession();

// Frontend receives only JWT token (no apiKey needed!)
const session = new KalturaAvatarSession(); // No apiKey!
await session.initSession({ sessionId, token });
// Control via backend API, display via SDK

Best for:

  • Production applications ✅
  • Server-to-server architecture
  • Better security (Kaltura Session hidden)
  • Separation of concerns
  • Scalable applications
Recommendation

For any production application, use API-based control. The apiKey parameter is optional—omit it when the backend creates the session.

Quick Decision Guide​

Choose SDK-based control if you:

  • Want the simplest integration
  • Are building a prototype or demo
  • Have a client-side only application
  • Need to get started quickly

Choose API-based control if you:

  • Are building a production application
  • Want better security
  • Prefer separation of concerns
  • Need server-side control and validation

Key Features​

  • WebRTC Streaming: Real-time avatar video
  • Text-to-Speech: Send plain text for avatar to speak with configured voice
  • Audio Support: Send audio files for avatar to speak
  • Production Ready: Comprehensive error handling and state management

Browser Support​

  • Chrome/Edge 80+
  • Firefox 75+
  • Safari 14+
  • Requires WebRTC support

Next Steps​

Ready to get started? Choose your path:

  1. Prerequisites - Check requirements and browser support
  2. Choosing Your Approach - Detailed comparison and decision guide
  3. SDK Quick Start - Get running in 5 minutes with SDK-only
  4. API Quick Start - Get running with API-based control (recommended)

Or jump directly to: