Create an Avatar and an Agent

← Back to Agent Components

Create an Avatar

POST https://api.avatar.us.kaltura.ai/v1/avatar/create

{
  "voice": { "id": "KbakCphLGyrStJ2sp8mp", "speed": 1.0 },
  "visual": {
    "id": "f5a6b7c8-d9e0-4f1a-2b3c-4d5e6f7a8b9c",
    "motionControl": { "speaking": 0.7, "nonSpeaking": 0.2 }
  },
  "name": "Support rep"
}

Allowed ranges: voice.speed 0.5 to 1.5; motionControl.speaking and motionControl.nonSpeaking each 0.1 to 1.0 (keep nonSpeaking below speaking); name up to 255 characters. A value outside these ranges is a 400.

voice.id and visual.id come from the catalog (Catalog & Assets § Browse the Catalog). For your own portrait, upload it first and use the returned itemId as visual.id (§ Upload a Custom Visual, which also covers how to prepare the photo). Returns id (24-char hex). No adminTags on avatars: tag the parent agent instead (Management Operations § Avatars).

Leave openingPhrase unset. The intellect's opening_phrase sets the first, uninterruptible turn of every session (Configure an Intellect). provision() writes it there and creates the avatar without a phrase. An avatar-level openingPhrase is spoken only for a session whose intellect has none. Clear one with avatars.update({ id, openingPhrase: null }, ks). Where the phrase lives, how to personalize it with a template, and the silent-opening and kickoff pattern: Start the Conversation.

Three ways to get a visual

avatar/create needs exactly one of these to resolve a visual:

You cannot create an avatar from a face alone and add the background afterwards: a face and a background are required together at create time. Once the avatar exists, avatars.update accepts a background on its own (Management Operations § Avatars).

For background.type: 'color', value must be a plain 6-digit hex string (#RRGGBB) with no alpha channel. An 8-digit hex (#RRGGBBAA), rgba(...) or a CSS4 rgb(... / ...%) throws bad_request before any network call.

Whichever way you pick, the composed result is reflected in the created avatar's visual.composition and a fresh previewImageUrl/loadingVideoUrl (asset URLs, not the rendered live-session composite). Inspect those to see what was built. Changing the composition after create follows different rules: Management Operations § Avatars.

Faster path: pick a curated preset instead of assembling voice and visual by hand. mgmt.avatars.listTemplates(ks, opts) lists curated bundles, each pairing a voice with either a ready visual or a face/background pair. Pass the template's own id as templateId; if the template's face/background is not already a complete pair, add whichever half it is missing:

const templates = await mgmt.avatars.listTemplates(ks, { pageSize: 10 });
const t = templates[0]; // { id, name, voice: { id }, face: { id, imageUrl } }
await mgmt.avatars.create(
  { voice: t.voice, templateId: t.id, background: { type: 'color', value: '#ffffff' } },
  ks,
);

Compose from a custom Face and Background

Upload the two halves first (Catalog & Assets § Upload a custom Face or Background), then pass their ids as face.id and background.value:

const face = await mgmt.catalog.createFace(portraitBlob, { name: 'Support rep', genderPresentation: 'Feminine' }, ks);
const bg = await mgmt.catalog.createBackground(backdropBlob, { name: 'Office', genderPresentation: 'Feminine' }, ks);
await mgmt.avatars.create(
  { voice: { id: voiceItemId }, face: { id: face.itemId }, background: { type: 'visual', value: bg.itemId } },
  ks,
);

Unlike createVisual (a photo used directly, already a full custom digital twin), a Face/Background is only usable through the face and background composition. You cannot pass it as visual.id on its own.

Create an Agent

POST https://api.avatar.us.kaltura.ai/v1/agent/create

{
  "displayName": "StreamBot Support Agent",
  "intellect": {
    "intellectType": "genie",
    "id": 1389
  },
  "avatarIds": ["6a07d63d8ccd85cbfafc5416"],
  "adminTags": ["support"],
  "maxConversationLength": 900
}

Returns agentId (UUID). Save this.

Screen share

The agent can look at the user's screen and help with what it sees. Two steps:

1. Turn it on for the agent. The prompt tells the vision step what to report.

await mgmt.agents.update({ agentId, screenShare: { enabled: true, prompt: 'Describe code, errors and UI state.' } }, ks);

2. In the browser, call session.startScreenShare() from a click. The browser shows its screen picker.

shareButton.addEventListener('click', () => {
  if (session.screenSharing) session.stopScreenShare();
  else session.startScreenShare().catch((e) => { if (e.code !== 'screen_share_denied') throw e; });
});
session.on('screenShareChanged', ({ active }) => shareButton.setAttribute('aria-pressed', String(active)));

KalturaAgentSession has the same startScreenShare(), stopScreenShare(), screenSharing and screenShareChanged. In chat mode startScreenShare() throws screen_share_unsupported. A switchMode() ends a running share.

The SDK sends a JPEG still every 2 seconds until stopScreenShare(), disconnect() or the user's own "stop sharing" control. The agent reads the stills as text, so answers can lag by a few seconds.

A failed capture during a share arrives as a warning event with code screen_share_capture_failed, and the share continues. session.sendScreenShot(data) sends one still you captured yourself. Full app: examples/screen-share-agent.html.

Related docs