Choosing Your Approach

The Kaltura Avatar system offers two control approaches. This guide helps you choose the right one for your use case.

Quick Comparison

Feature	SDK-Based Control	API-Based Control
Complexity	Simple	Moderate
Security	Kaltura Session in client	Kaltura Session on server ✅
Architecture	Client-side only	Backend + Frontend
Best for	Demos, prototypes	Production apps ✅
Setup time	5 minutes	15 minutes
Control location	Browser	Server
Scalability	Limited	High ✅

SDK-Based Control

How It Works

┌──────────────────────────────┐
│      Browser                 │
│                              │
│  ┌────────────────────────┐  │
│  │ Client SDK             │  │
│  │ • Display avatar       │  │
│  │ • Control avatar       │  │
│  │ • KS in code           │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

All functionality runs in the browser. The SDK handles both display and control.

Code Example

import { KalturaAvatarSession } from '@unisphere/models-sdk-js';

const session = new KalturaAvatarSession('your-api-key', {
  baseUrl: 'https://api.avatar.us.kaltura.ai/v1/avatar-session',
});

await session.createSession({
  avatarId: 'avatar-123',
  videoContainerId: 'avatar-container',
});

await session.sayText('Hello from Kaltura Avatar!');

Pros

• Simple: Single SDK, no backend needed
• Fast to implement: Get running in 5 minutes
• Easy debugging: Everything in browser DevTools
• Perfect for demos: Quick prototypes and presentations

Cons

• Security risk: Kaltura Session exposed in client code
• Limited control: Can't validate/modify from server
• No audit trail: Can't log server-side actions
• Client dependency: Relies on client implementation

When to Use

✅ Prototypes and demos
✅ Internal tools (no public access)
✅ Learning and experimentation
✅ Client-only applications

❌ Public-facing production apps
❌ Apps requiring server-side validation
❌ Apps needing audit trails

API-Based Control (Recommended)

How It Works

┌──────────────────────────────┐
│      Browser                 │
│                              │
│  ┌────────────────────────┐  │
│  │ Client SDK             │  │
│  │ • Display avatar       │  │
│  │ • Receive token        │  │
│  └────────────────────────┘  │
└──────────────────────────────┘
                ↕
┌──────────────────────────────┐
│      Backend Server          │
│                              │
│  ┌────────────────────────┐  │
│  │ Control API            │  │
│  │ • Create sessions      │  │
│  │ • Control avatar       │  │
│  │ • KS secure            │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

Backend controls the avatar via API, frontend displays it.

SDK apiKey Parameter

The KalturaAvatarSession constructor takes an optional apiKey parameter:

• Pass it for FE-only control (new KalturaAvatarSession('your-ks'))
• Omit it for BE/FE split control (new KalturaAvatarSession() or new KalturaAvatarSession(undefined, ...))

When using API-based control, the backend has the Kaltura Session. The frontend only gets a JWT token via initSession().

Code Example

Backend (Node.js):

// Backend - Create session (Kaltura Session stays secure!)
const response = await fetch('https://api.avatar.us.kaltura.ai/v1/avatar-session/create', {
  method: 'POST',
  headers: {
    Authorization: `ks ${process.env.AVATAR_KS}`, 
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    clientId: 'kaltura-avatar-sdk',
    visualConfig: { id: 'avatar-123' },
    voiceConfig: { id: 'voice-456', modelId: 'eleven_flash_v2_5' },
  }),
});

const { sessionId, token } = await response.json();

// Send JWT token to frontend (safe to expose)
res.json({ sessionId, token });

Frontend:

// Frontend - Display avatar (NO apiKey needed!)
import { KalturaAvatarSession } from '@unisphere/models-sdk-js';

const { sessionId, token } = await fetch('/api/create-avatar-session').then((r) => r.json());

// Create SDK instance WITHOUT apiKey (backend already created session)
const session = new KalturaAvatarSession(undefined, {
  baseUrl: 'https://api.avatar.us.kaltura.ai/v1/avatar-session',
});

// Initialize with credentials from backend
await session.initSession(
  { sessionId, token },
  { videoContainerId: 'avatar-container' }
);

// Control happens via backend API, SDK handles display only

Pros

• Secure: Kaltura Session stays on server
• Separation: Backend controls, frontend displays
• Validation: Server validates all actions
• Audit trail: Log all avatar interactions
• Scalable: Backend can manage multiple sessions

Cons

• More complex: Requires backend infrastructure
• Additional code: Backend and frontend coordination
• Network latency: Extra hop through backend

When to Use

✅ Production applications (recommended)
✅ Public-facing websites
✅ Apps requiring security
✅ Apps needing server-side logic
✅ Apps with user authentication
✅ Apps requiring audit logs

Can I Switch Later?

Yes! The Client SDK always handles display. You can:

1. Start with SDK-based control (quick)
2. Switch to API-based control (production)

Migration is straightforward:

• Keep Client SDK for display
• Move control calls from SDK to API
• Store Kaltura Session on backend

Hybrid Approach

You can also use a hybrid approach:

• Client SDK displays avatar
• Some controls via SDK (simple actions)
• Critical controls via API (validated actions)

This gives flexibility but adds complexity.

Next Steps

Ready to Start with SDK-Based Control?

SDK Quick Start →

Ready to Start with API-Based Control?

API Quick Start →

Need More Details?

• Client SDK Reference - Full SDK documentation
• Control API Reference - Full API documentation