Create Session

Create a new avatar session.

Endpoint

POST /v1/avatar-session

Authentication

Header: Authorization

Authorization: KS your-kaltura-session-here

Security

Never expose your Kaltura Session in client-side code. Always call this endpoint from your backend server.

Request Body

{
  "visualConfig": {
    "avatarId": "string"
  },
  "voiceConfig": {
    "id": "string",
    "speed": number
  }
}

Parameters

Field	Type	Required	Description
visualConfig	object	Yes	Avatar visual configuration
visualConfig.avatarId	string	Yes	ID of the avatar to use
voiceConfig	object	No	Voice configuration for TTS
voiceConfig.id	string	No	ID of the voice to use
voiceConfig.speed	number	No	Speech speed multiplier (e.g., 1.0, 1.5)

Response

Success (200)

{
  "success": true,
  "sessionId": "string",
  "token": "string"
}

Field	Type	Description
success	boolean	Always true on success
sessionId	string	Unique session identifier
token	string	JWT token for session authentication

Error Responses

401 Unauthorized

{
  "success": false,
  "error": "Invalid Kaltura Session"
}

403 Forbidden

{
  "success": false,
  "error": "Kaltura Session not authorized"
}

500 Server Error

{
  "success": false,
  "error": "Internal server error"
}

Examples

cURL

curl -X POST https://api.avatar.us.kaltura.ai/v1/avatar-session \
  -H "Authorization: KS your-kaltura-session" \
  -H "Content-Type: application/json" \
  -d '{
    "visualConfig": {
      "avatarId": "avatar-123"
    },
    "voiceConfig": {
      "id": "voice-456",
      "speed": 1.0
    }
  }'

JavaScript (fetch)

const response = await fetch('https://api.avatar.us.kaltura.ai/v1/avatar-session', {
  method: 'POST',
  headers: {
    Authorization: `KS ${process.env.AVATAR_KS}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    visualConfig: {
      avatarId: 'avatar-123',
    },
    voiceConfig: {
      id: 'voice-456',
      speed: 1.0,
    },
  }),
});

const data = await response.json();
console.log('Session ID:', data.sessionId);
console.log('Token:', data.token);

Node.js (axios)

const axios = require('axios');

const response = await axios.post(
  'https://api.avatar.us.kaltura.ai/v1/avatar-session',
  {
    visualConfig: {
      avatarId: 'avatar-123',
    },
    voiceConfig: {
      id: 'voice-456',
    },
  },
  {
    headers: {
      Authorization: `KS ${process.env.AVATAR_KS}`,
      'Content-Type': 'application/json',
    },
  }
);

const { sessionId, token } = response.data;

Python (requests)

import requests
import os

response = requests.post(
    'https://api.avatar.us.kaltura.ai/v1/avatar-session',
    headers={
        'Authorization': f'KS {os.environ.get("AVATAR_KS")}',
        'Content-Type': 'application/json'
    },
    json={
        'visualConfig': {
            'avatarId': 'avatar-123'
        },
        'voiceConfig': {
            'id': 'voice-456',
            'speed': 1.0
        }
    }
)

data = response.json()
session_id = data['sessionId']
token = data['token']

Usage Notes

Session Lifecycle

After creating a session:

1. Initialize client - Call init-client to get WebRTC config
2. Use the session - Call other endpoints to control the avatar
3. Keep alive - Send keep-alive every 10 seconds
4. End session - Call end-session when done

Token Usage

The returned JWT token must be used for all subsequent API calls for this session:

// Use the token in Authorization header
fetch(`https://api.avatar.us.kaltura.ai/v1/avatar-session/${sessionId}/say-text`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: 'Hello!' }),
});

Voice Configuration

The voiceConfig is optional. If not provided, the default voice will be used.

Speed values:

• 1.0 - Normal speed (default)
• 0.5 - Half speed (slower)
• 1.5 - 1.5x speed (faster)
• 2.0 - Double speed (very fast)

Error Handling

Always check for errors:

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  console.error('Failed to create session:', error.error);
  throw new Error(error.error);
}

const data = await response.json();

Next Steps

After creating a session:

1. Initialize Client - Get WebRTC configuration
2. Say Text - Make the avatar speak
3. End Session - Clean up when done