📦 Catalog Service

The catalog is your library of faces and voices. Mix and match to create unique avatars.

Every avatar in the platform is built from two types of catalog items:

👁️ Visual items — the avatar's appearance (uploaded as an image or processed visual asset)
🗣️ Voice items — the avatar's voice (uploaded as a reference audio sample)

You browse, upload, and manage these building blocks through the Catalog Service. Once you have the catalog item IDs you need, head to the Avatar Service to combine them.

Base route: POST /service/catalog-item/action/{actionName}

Presets vs. custom items

The catalog contains both preset items (provided by Kaltura, with partnerId: 0) and custom items (uploaded by you, with your partnerId). List the catalog to see what presets are available before uploading your own.

Data Model

👁️ Visual Items
🗣️ Voice Items

A visual catalog item represents an avatar's appearance.

Field	Type	Description
`itemId`	string	Unique catalog item identifier
`type`	`'Visual'`	Item type
`attributes.visual.background`	`'Color'` \| `'Image'`	Background type
`attributes.visual.name`	string	Display name for this visual
`attributes.visual.genderPresentation`	`'Masculine'` \| `'Feminine'`	Gender presentation
`attributes.visual.skinTone`	`'Light'` \| `'LightMedium'` \| `'MediumTan'`	Skin tone
`attributes.visual.ageGroup`	`'YoungAdult'` \| `'OlderAdult'`	Age group
`attributes.visual.hairColor`	`'Black'` \| `'Brown'` \| `'Blonde'` \| `'Red'` \| `'Gray'`	Hair color
`attributes.visual.hairStyle`	string[]	Hair style tags
`attributes.visual.clothing`	string[]	Clothing style tags
`attributes.visual.glasses`	boolean	Whether the avatar wears glasses
`imageUrl`	string	Thumbnail preview URL
`agentScope`	string	Restricts item to a specific agent (optional)
`adminTags`	string[]	Tags for filtering and organization
`createdBy`	string	User who created this item
`createdAt`	Date	Creation timestamp
`updatedAt`	Date	Last modification timestamp

A voice catalog item represents an avatar's voice.

Field	Type	Description
`itemId`	string	Unique catalog item identifier
`type`	`'Voice'`	Item type
`attributes.voice.name`	string	Display name for this voice
`attributes.voice.description`	string	Description of the voice's character
`attributes.voice.language`	string	Language code (e.g., `en-US`, `es-ES`)
`imageUrl`	string	Optional preview image
`agentScope`	string	Restricts item to a specific agent (optional)
`adminTags`	string[]	Tags for filtering and organization
`createdBy`	string	User who created this item
`createdAt`	Date	Creation timestamp
`updatedAt`	Date	Last modification timestamp

Actions

`get` — Retrieve a Catalog Item

POST /service/catalog-item/action/get

Request body:

{
  "itemId": "catalog_item_id_123"
}

Field	Type	Required	Description
`itemId`	string	✅ Yes	The catalog item ID to retrieve

Response:

{
  "itemId": "catalog_item_id_123",
  "type": "Visual",
  "attributes": {
    "visual": {
      "name": "Professional Maya",
      "background": "Color",
      "genderPresentation": "Feminine",
      "skinTone": "LightMedium",
      "ageGroup": "YoungAdult",
      "hairColor": "Brown",
      "hairStyle": ["straight", "shoulder-length"],
      "clothing": ["business-casual"],
      "glasses": false
    }
  },
  "imageUrl": "https://cdn.kaltura.com/catalog/preview-maya.jpg",
  "adminTags": ["production"],
  "createdBy": "admin@company.com",
  "createdAt": "2024-01-05T08:00:00.000Z",
  "updatedAt": "2024-01-05T08:00:00.000Z"
}

Examples:

cURL
curl -X POST "https://YOUR_API_HOST/service/catalog-item/action/get" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "itemId": "catalog_item_id_123" }'

JavaScript
const item = await fetch('https://YOUR_API_HOST/service/catalog-item/action/get', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ itemId: 'catalog_item_id_123' }),
}).then((res) => res.json());

`list` — List Catalog Items

POST /service/catalog-item/action/list

The most powerful action for browsing the catalog. Filter by type, language, tags, or agent scope.

Request body:

{
  "filter": {
    "typeEqual": "Visual",
    "languageEqual": "en-US",
    "adminTagsIn": ["production"]
  },
  "agentScope": "550e8400-e29b-41d4-a716-446655440000",
  "pager": {
    "offset": 0,
    "limit": 30
  },
  "orderBy": "-createdAt"
}

Field	Type	Required	Description
`filter.typeEqual`	`'Visual'` \| `'Voice'`	No	Filter to only visual or only voice items
`filter.languageEqual`	string	No	Filter voices by language code
`filter.itemIdEqual`	string	No	Filter to a specific item ID
`filter.adminTagsIn`	string[]	No	Filter by any of these admin tags
`agentScope`	string	No	Include agent-scoped items alongside global items
`pager.offset`	number	No	Pagination offset (default: 0)
`pager.limit`	number	No	Max results per page (default: 30)
`orderBy`	string	No	Sort order: `+createdAt` or `-createdAt`

Response:

{
  "objects": [ ... ],
  "totalCount": 24
}

Examples:

cURL — list all English voices
curl -X POST "https://YOUR_API_HOST/service/catalog-item/action/list" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "typeEqual": "Voice",
      "languageEqual": "en-US"
    },
    "pager": { "offset": 0, "limit": 30 }
  }'

JavaScript — browse all visual items
const { objects, totalCount } = await fetch('https://YOUR_API_HOST/service/catalog-item/action/list', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { typeEqual: 'Visual' },
    pager: { offset: 0, limit: 30 },
    orderBy: '-createdAt',
  }),
}).then((res) => res.json());

console.log(`Found ${totalCount} visual items in the catalog`);
objects.forEach((item) => {
  console.log(`- ${item.itemId}: ${item.attributes.visual?.name}`);
});

`create` — Upload a Catalog Item

POST /service/catalog-item/action/create

🔀 This one's different — it uses multipart/form-data!

Unlike the other actions (which use JSON), create and update use multipart/form-data to support file uploads. The attributes field is sent as a JSON string within the form data.

Content-Type: multipart/form-data

Form fields:

Field	Type	Required	Description
`file`	File	✅ Yes	Image file for visual items, or audio file for voice items
`agentScope`	string	No	Restrict this item to a specific agent UUID
`adminTags`	string (JSON array)	No	Tags for filtering, e.g. `["production","english"]`
`attributes`	string (JSON)	No	Attributes JSON string (see below)

📏 File requirements

Item Type	Accepted Formats	Max Size
Visual	`image/*` (JPG, PNG, WebP, etc.)	10 MB
Voice	`audio/mpeg` (MP3)	10 MB

Files outside these types or over 10 MB will return a 400 error.

Attributes JSON for visual items:

{
  "visual": {
    "name": "Professional Maya",
    "background": "Color",
    "genderPresentation": "Feminine",
    "skinTone": "LightMedium",
    "ageGroup": "YoungAdult",
    "hairColor": "Brown",
    "hairStyle": ["straight", "shoulder-length"],
    "clothing": ["business-casual"],
    "glasses": false
  }
}

Attributes JSON for voice items:

{
  "voice": {
    "name": "Emma",
    "description": "Warm, professional female voice",
    "language": "en-US"
  }
}

Examples:

cURL — visual item
cURL — voice item
JavaScript — visual item
JavaScript — voice item

curl -X POST "https://YOUR_API_HOST/service/catalog-item/action/create" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -F "file=@/path/to/avatar-image.jpg" \
  -F 'adminTags=["production"]' \
  -F 'attributes={
    "visual": {
      "name": "Professional Maya",
      "background": "Color",
      "genderPresentation": "Feminine",
      "skinTone": "LightMedium",
      "ageGroup": "YoungAdult",
      "hairColor": "Brown",
      "glasses": false
    }
  }'

curl -X POST "https://YOUR_API_HOST/service/catalog-item/action/create" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -F "file=@/path/to/voice-sample.mp3" \
  -F 'attributes={
    "voice": {
      "name": "Emma",
      "description": "Warm, professional female voice",
      "language": "en-US"
    }
  }'

const formData = new FormData();
formData.append('file', imageFile); // File object from <input type="file"> or fs.readFileSync
formData.append('adminTags', JSON.stringify(['production']));
formData.append(
  'attributes',
  JSON.stringify({
    visual: {
      name: 'Professional Maya',
      background: 'Color',
      genderPresentation: 'Feminine',
      skinTone: 'LightMedium',
      ageGroup: 'YoungAdult',
      hairColor: 'Brown',
      glasses: false,
    },
  }),
);

const newItem = await fetch('https://YOUR_API_HOST/service/catalog-item/action/create', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
    // ⚠️ Do NOT set Content-Type manually — the browser sets it with the boundary
  },
  body: formData,
}).then((res) => res.json());

console.log(`Uploaded visual item: ${newItem.itemId}`);

const formData = new FormData();
formData.append('file', audioFile); // MP3 File object
formData.append(
  'attributes',
  JSON.stringify({
    voice: {
      name: 'Emma',
      description: 'Warm, professional female voice',
      language: 'en-US',
    },
  }),
);

const newItem = await fetch('https://YOUR_API_HOST/service/catalog-item/action/create', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
  },
  body: formData,
}).then((res) => res.json());

console.log(`Uploaded voice item: ${newItem.itemId}`);

Error responses:

Status	Description
`400`	Invalid file type, file too large, or malformed attributes JSON
`401`	Invalid or expired KS token
`403`	Missing required subscription feature (`AVATAR_STUDIO` or `PersonalAvatar`)

`update` — Update a Catalog Item

POST /service/catalog-item/action/update

Update metadata or replace the file of an existing catalog item.

Content-Type: multipart/form-data

Form fields:

Field	Type	Required	Description
`itemId`	string	✅ Yes	The item to update
`file`	File	No	Replace the existing file
`agentScope`	string \| `null`	No	Update or remove agent scope (`null` to make global)
`adminTags`	string (JSON array)	No	Replace the full tags list
`attributes`	string (JSON)	No	Replace the full attributes object

Examples:

cURL — update tags only
curl -X POST "https://YOUR_API_HOST/service/catalog-item/action/update" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -F "itemId=catalog_item_id_123" \
  -F 'adminTags=["production","v2"]'

JavaScript — update tags only
const formData = new FormData();
formData.append('itemId', 'catalog_item_id_123');
formData.append('adminTags', JSON.stringify(['production', 'v2']));

await fetch('https://YOUR_API_HOST/service/catalog-item/action/update', {
  method: 'POST',
  headers: { Authorization: `KS ${ksToken}` },
  body: formData,
});

`delete` — Delete a Catalog Item

POST /service/catalog-item/action/delete

Permanently deletes a catalog item. This cannot be undone.

Request body:

{
  "itemId": "catalog_item_id_123"
}

Field	Type	Required	Description
`itemId`	string	✅ Yes	The catalog item to delete

Response:

{
  "itemId": "catalog_item_id_123"
}

⚠️ Check avatars before deleting

If you delete a catalog item that's referenced by an avatar (voice.id or visual.id), the avatar will still hold a reference to the deleted ID. Remove or update those avatar references first to avoid broken configurations.

Examples:

cURL
curl -X POST "https://YOUR_API_HOST/service/catalog-item/action/delete" \
  -H "Authorization: KS YOUR_KS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "itemId": "catalog_item_id_123" }'

JavaScript
await fetch('https://YOUR_API_HOST/service/catalog-item/action/delete', {
  method: 'POST',
  headers: {
    Authorization: `KS ${ksToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ itemId: 'catalog_item_id_123' }),
});

Usage Notes

Agent Scope

The agentScope field restricts a catalog item to a specific agent. When listing catalog items with an agentScope parameter, you'll get:

All unscoped (global) items
All items scoped to that agent

This is useful for giving individual agents exclusive avatar options while still having a shared pool of global items.

Admin Tags

Use adminTags to organize your catalog for filtering. Common conventions:

production / staging / test — environment markers
Language codes: en, es, fr
Style categories: professional, casual, animated
Version markers: v1, v2

Visual Attributes as Metadata

The visual attributes (background, skinTone, hairColor, etc.) are metadata — they describe the visual for search/filtering purposes, but they don't affect the rendered output. The actual visual is determined by the uploaded file. Tag your catalog items accurately so they're discoverable when filtering by genderPresentation, skinTone, etc.

Next Steps

🎭 Avatar Service — Use your itemId values to create avatars
🛠️ Workflows — See the complete end-to-end setup with catalog items

Data Model​

Actions​

get — Retrieve a Catalog Item​

list — List Catalog Items​

create — Upload a Catalog Item​

update — Update a Catalog Item​

delete — Delete a Catalog Item​

Usage Notes​

Agent Scope​

Admin Tags​

Visual Attributes as Metadata​

Next Steps​

Data Model

Actions

`get` — Retrieve a Catalog Item

`list` — List Catalog Items

`create` — Upload a Catalog Item

`update` — Update a Catalog Item

`delete` — Delete a Catalog Item

Usage Notes

Agent Scope

Admin Tags

Visual Attributes as Metadata

Next Steps