Skip to main content

​
Overview

An Avatar is a pre-processed video asset used for sessions. Avatars are organized into:
  • Characters: top-level entries with parent_id = null
  • Looks: session-ready entries with parent_id = <character_id>
Sessions must be created with a look (an avatar with parent_id set).
What Avatars Do:
  • Provide the visual appearance for video sessions
  • Can be private (your account only) or public (shared)
  • Support multiple languages and styles
  • Generate realistic talking head animations from audio

​
Fields

The Avatar object represents a visual avatar used in video sessions.
FieldTypeDescription
avatar_idstringUnique avatar identifier (starts with avat_)
namestringDisplay name of the avatar
preview_img_urlstringURL to the avatar’s preview image
parent_idstring | nullIf set, this avatar is a look of the character with this ID
looks_countnumberFor characters, the number of available looks
video_urlstringFor looks, a signed preview video URL (when available)
is_favoriteintegerWhether avatar is marked as favorite (1 = yes, 0 = no)
is_publicintegerWhether avatar is publicly accessible (1 = yes, 0 = no)
activeintegerWhether the avatar is active (1 = active, 0 = inactive)
created_atstringISO 8601 timestamp of when the avatar was created
updated_atstringISO 8601 timestamp of when the avatar was last updated

​
Example

{
  "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
  "name": "Professional Avatar",
  "preview_img_url": "https://res.cloudinary.com/example/image/upload/v123/avatars/avatar1.png",
  "parent_id": null,
  "looks_count": 3,
  "is_favorite": 1,
  "is_public": 0,
  "active": 1,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

​
Notes

  • Avatar IDs are prefixed with avat_ for easy identification
  • Favorites are user-specific - each user can mark different avatars as favorites
  • Public avatars can be accessed by any authenticated user
  • Preview images are optimized for display in avatar selection interfaces