---
title: SDK Quick Start
url: https://docs.kaltura.com/docs/conversational-agents/agentic-avatars-sdk/quick-start-sdk
---


## SDK Quick Start

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

:::info Best For
This approach is perfect for demos, prototypes, and learning. For production, see the [API Quick Start](/docs/conversational-agents/agentic-avatars-sdk/quick-start-api) guide.
:::

### Step 1: Install the SDK

```bash
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](/docs/getting-started/authentication/ks-overview) to generate one.

:::danger Security Warning
Never expose your Kaltura Session in client-side code for production applications. Use the [API-based approach](/docs/conversational-agents/agentic-avatars-sdk/quick-start-api) to keep the KS server-side.
:::

### Step 3: Prepare Your HTML

Create a container div where the avatar will be displayed:

```html
<!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`:

```javascript
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();
```

:::warning 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](/docs/conversational-agents/agentic-avatars-sdk/quick-start-api) for production setups.
:::

### Step 5: Run Your Application

Using a bundler (Vite/Webpack):

```bash
npm run dev
```

Using vanilla JS with a static server:

```bash
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

```javascript
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](/docs/conversational-agents/agentic-avatars-sdk/quick-start-api) 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()`:

```javascript
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

```typescript
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](/docs/conversational-agents/agentic-avatars-sdk/client-sdk-installation) — full SDK documentation
- [Control API](/docs/conversational-agents/agentic-avatars-sdk/control-api-overview) — server-side API reference
- [Examples](/docs/conversational-agents/agentic-avatars-sdk/examples-simple-client-side) — code samples and integrations
- [API Quick Start](/docs/conversational-agents/agentic-avatars-sdk/quick-start-api) — secure API-based control for production