Skip to main content
PUT
update avatar

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string<uuid>
required

Avatar ID

Body

application/json

Fields to update on the avatar. Only displayName is editable.

displayName
string
required

New display name for the avatar

Response

Successfully updated avatar

A face preset that a persona can use as its visual representation.

id
string<uuid>

Unique identifier for the avatar.

displayName
string

Human-readable name shown in the Lab and share links.

variantName
string

Name of the specific variant (e.g. lighting or pose) within the avatar family.

imageUrl
string<uri>

URL of the still image used as a preview of the avatar.

landscapeImageUrl
string<uri> | null

Preview image cropped exactly as the engine frames landscape (1152x768) output. Use this when displaying the avatar at a landscape aspect ratio. For avatars with legacy landscape source images this is the same as imageUrl.

portraitImageUrl
string<uri> | null

Preview image cropped exactly as the engine frames portrait (768x1152) output. Use this when starting a session with portrait videoWidth/videoHeight. null when the avatar cannot render portrait output.

videoUrl
string<uri> | null

Signed URL for a muted MP4 preview of the avatar, if one exists. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. null when the preview is unavailable or still generating.

idleVideoUrl
string<uri> | null

Signed URL for a muted idling-loop MP4 of the avatar, if one exists. The URL expires after 1 hour; re-fetch the avatar to get a fresh URL. null when unavailable or still generating.

createdAt
string<date-time>

Timestamp when the avatar was created.

updatedAt
string<date-time>

Timestamp when the avatar was last updated.

createdByOrganizationId
string | null

ID of the organization that created the avatar, or null for stock avatars. IDs may be either UUIDs or nanoid-style strings depending on when the organization was created.

availableVersions
string[]

Avatar models this avatar can be used with. Pass one of these values as avatarModel when creating a persona or starting a session.

activeVersion
string | null

Avatar model used by default when no explicit avatarModel is requested.

description
string | null

AI-generated description of the avatar's appearance, setting, and style. null if metadata generation has not completed.

displayTags
string[]

Curated tags describing the avatar. Empty array if metadata generation has not completed.

renderStyle
enum<string>

Render style of the avatar. unknown covers custom avatars and avatars whose metadata has not yet been generated.

Available options:
realistic,
animated_3d,
illustrated,
unknown
Last modified on July 10, 2026