Avatar Templates & Configuration - Avatar Videos

Avatar Templates & Configuration

Before creating a video, you need an avatar — a specific AI presenter with a chosen background. Avatars are built in two steps:

1. Pick a template — Each template is a predefined AI character with a unique face, voice, and speaking style. You select from the available set of predefined characters.
2. Configure it as an avatar — Combine the template with a background (solid color, library image, or custom image from your Kaltura account). This creates a reusable avatar configuration tied to your user.

The avatar ID is then passed to video.add to assign the presenter for that video project.

Step 1: List Available Templates

Call avatarTemplate/list to get the full set of available AI characters. Each template has an id (used when creating avatars) and a display name:

curl -s -X POST "$AVATAR_API/avatarTemplate/list" \
  -H "Authorization: Bearer $KS" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "objects": [
    { "id": "jane", "name": "Jane" },
    { "id": "adam", "name": "Adam" },
    { "id": "amir", "name": "Amir" }
  ],
  "totalCount": 36
}

The id field (e.g., "jane", "adam") is what you pass as templateId when creating an avatar. The full set of 36 templates: adam, amir, ben, cristina, david, derek, dylan, elizabeth, gloria, harper, harry, henry, james, jane, jason, jennifer, julia, kevin, larry, lisa, maria, maya, mia, miguel, ming, rita, sam, sara, sharon, sophia, taylor, theodore, tim, victoria, william, yasmin.

Step 2: Create an Avatar (avatar/upsert)

An avatar pairs a template with a background. The upsert action is idempotent — if an avatar with the same template + background combination already exists for your user, it returns the existing one instead of creating a duplicate. This means you can safely call upsert every time without checking for existing avatars first.

AVATAR_RESULT=$(curl -s -X POST "$AVATAR_API/avatar/upsert" \
  -H "Authorization: Bearer $KS" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "jane",
    "background": { "type": "color", "color": "#CEEEDB" }
  }')
AVATAR_ID=$(echo "$AVATAR_RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "Avatar ID: $AVATAR_ID"

Request fields:

Field	Type	Required	Description
templateId	string	yes	One of the template IDs from avatarTemplate/list (e.g., "jane", "adam")
background	object	yes	Background configuration — structure depends on the type field (see below)

background object:

Field	Type	Required	Description
type	string	yes	One of: "color", "library", "entry"
color	string	if type="color"	Hex color code (e.g., "#CEEEDB", "#FFFFFF")
id	string	if type="library"	Predefined background image ID (lowercase alphanumeric and hyphens only, e.g., "office-1")
entryId	string	if type="entry"	Kaltura entry ID of a custom background image from your account

Background type examples:

# Solid color background
'{ "templateId": "adam", "background": { "type": "color", "color": "#1A1A2E" } }'

# Predefined library image
'{ "templateId": "adam", "background": { "type": "library", "id": "office-1" } }'

# Custom image from your Kaltura account
'{ "templateId": "adam", "background": { "type": "entry", "entryId": "0_bg7x9k2m" } }'

Response fields:

Field	Type	Description
id	string	The avatar ID — pass this as avatarId when creating video projects
templateId	string	The template used
background	object	The background configuration
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp

Get an Avatar

Retrieve an existing avatar configuration by ID:

curl -s -X POST "$AVATAR_API/avatar/get" \
  -H "Authorization: Bearer $KS" \
  -H "Content-Type: application/json" \
  -d "{ \"id\": \"$AVATAR_ID\" }"

Returns the same response structure as avatar/upsert.

Preview an Avatar

Get a PNG image showing how the avatar looks with its configured background. Use this to display a visual preview before creating videos:

curl -s -X POST "$AVATAR_API/avatar/preview" \
  -H "Authorization: Bearer $KS" \
  -H "Content-Type: application/json" \
  -d "{ \"id\": \"$AVATAR_ID\" }" \
  --output avatar_preview.png

Returns image/png binary data. The preview shows the avatar character composited on the configured background.