---
title: Avatar Templates & Configuration
url: https://docs.kaltura.com/docs/conversational-agents/avatar-videos/avatar-templates
---

## 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`:

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

**Response:**

```json
{
  "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.

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

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

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

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