SDK Quick Start - Agentic Avatars SDK

SDK Quick Start

Get up and running with Kaltura Avatar in 5 minutes using SDK-based control.

Best For

This approach is perfect for demos, prototypes, and learning. For production, see the API Quick Start guide.

Step 1: Install the SDK

npm install @unisphere/models-sdk-js

Step 2: Get Your Kaltura Session (KS)

You'll need a Kaltura Session for authentication. Follow the Kaltura Session Guide to generate one.

Security Warning

Never expose your Kaltura Session in client-side code for production applications. Use the API-based approach to keep the KS server-side.

Step 3: Prepare Your HTML

Create a container div where the avatar will be displayed:

<!DOCTYPE html>
<html>
  <head>
    <title>Kaltura Avatar Demo</title>
    <style>
      #avatar-container {
        width: 512px;
        height: 512px;
        border: 2px solid #ccc;
        border-radius: 8px;
        overflow: hidden;
      }
    </style>
  </head>
  <body>
    <h1>Kaltura Avatar Demo</h1>
    <div id="avatar-container"></div>
    <div style="margin-top: 20px;">
      <button id="speak-btn">Make Avatar Speak</button>
      <button id="interrupt-btn">Interrupt</button>
      <button id="end-btn">End Session</button>
    </div>
    <script src="main.js" type="module"></script>
  </body>
</html>

Step 4: Create the Avatar Session

Create a file named main.js:

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

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

session.on('stateChange', (state) => {
  console.log('Session state:', state);
});

session.on('connectionChange', (state) => {
  console.log('Connection state:', state);
});

session.on('error', (error) => {
  console.error('Error:', error.message);
});

async function startAvatar() {
  try {
    await session.createSession({
      visualId: 'visual-123',
      voiceId: 'voice-456',
      videoContainerId: 'avatar-container',
    });

    console.log('Avatar session started!');
    console.log('Session ID:', session.getSessionId());

    await session.sayText('Hello! I am your Kaltura Avatar. How can I help you today?');
  } catch (error) {
    console.error('Failed to start avatar:', error);
  }
}

document.getElementById('speak-btn').addEventListener('click', async () => {
  await session.sayText('This is a test message from the avatar.');
});

document.getElementById('interrupt-btn').addEventListener('click', async () => {
  await session.interrupt();
  console.log('Avatar interrupted');
});

document.getElementById('end-btn').addEventListener('click', async () => {
  await session.endSession();
  console.log('Session ended');
});

startAvatar();

API Key Security

This example includes the API key in client code. This is OK for demos but NOT for production. Use the API Quick Start for production setups.

Step 5: Run Your Application

Using a bundler (Vite/Webpack):

npm run dev

Using vanilla JS with a static server:

npx serve .

Open your browser and the avatar should appear.

What Just Happened?

1. Created SDK instance — configured with Kaltura Session and base URL
2. Created avatar session — specified visualId and videoContainerId
3. SDK automatically:
   • Called the backend to create a session
   • Established WebRTC connection
   • Created video element inside the container
   • Started keep-alive (every 10 seconds)
4. Made avatar speak — using sayText()

SDK-Only vs Backend-Created Sessions

Aspect	SDK-Only	Backend-Created
Who creates session	SDK (browser)	Your backend server
apiKey needed	Yes, in client code	No, backend has it
Constructor	new KalturaAvatarSession({ apiKey: 'your-ks' })	new KalturaAvatarSession() (no apiKey)
Initialization	createSession()	initSession({sessionId, token})
Security	KS exposed	KS hidden ✅
Best for	Demos, internal tools	Production apps

Switching to Backend-Created Sessions

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

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

await session.initSession(
  { sessionId, token },
  { videoContainerId: 'avatar-container' }
);

await session.sayText('Hello!');

See the API Quick Start for the complete backend setup.

Common Issues

Avatar not displaying

Check the browser console for errors. Common causes:

• Invalid API key
• Incorrect baseUrl
• WebRTC not supported in browser
• Firewall blocking WebRTC

Video element not found

Make sure the container exists before calling createSession():

document.addEventListener('DOMContentLoaded', async () => {
  await session.createSession({ videoContainerId: 'avatar-container' });
});

Connection timeout

• Check network connectivity
• Verify TURN servers are accessible (whitelist 3.41.177.176/29)

Complete Working Example

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

async function runAvatarDemo() {
  const session = new KalturaAvatarSession({
    apiKey: 'your-api-key',
    baseUrl: 'https://api.avatar.us.kaltura.ai/',
    logLevel: 'info',
  });

  session.on('stateChange', (state: SessionState) => {
    console.log('State changed:', state);
    document.getElementById('status').textContent = state;
  });

  session.on('error', (error: AvatarError) => {
    console.error('SDK Error:', error.code, error.message);
    alert(`Error: ${error.message}`);
  });

  try {
    await session.createSession({
      visualId: 'visual-123',
      voiceId: 'voice-456',
      videoContainerId: 'avatar-container',
    });

    console.log('Avatar ready!');
    console.log('Session ID:', session.getSessionId());

    await session.sayText('Welcome to Kaltura Avatar! I am ready to help you.');

    const speakBtn = document.getElementById('speak-btn');
    speakBtn.onclick = async () => {
      await session.sayText('You clicked the speak button. This is a demo message.');
    };
  } catch (error) {
    if (error instanceof AvatarError) {
      console.error('Avatar Error:', error.code, error.message);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', runAvatarDemo);
} else {
  runAvatarDemo();
}

Next Steps

• Client SDK Reference — full SDK documentation
• Control API — server-side API reference
• Examples — code samples and integrations
• API Quick Start — secure API-based control for production