Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt

Use this file to discover all available pages before exploring further.

An Avatar is the digital human AvatarKit renders on screen. It is a bundle of avatar assets identified by an Avatar ID — not the conversation, not audio, and not motion data. The client-side path is: 
Avatar ID -> AvatarManager.load() -> Avatar -> AvatarView -> AvatarController

​
Avatar ID

An Avatar ID is the stable identifier your app uses to load a character. For stock characters, copy it from a Public Avatar in Spatius Studio.
avatars
1

Browse Public Avatars

Go to Spatius Studio.
2

Copy the Avatar ID

Hover over an avatar card and click the copy icon.
3

Load the Avatar

Pass the Avatar ID to AvatarManager.load(...).
Custom Avatars are coming soon. They will use the same Avatar ID loading path.

​
AvatarManager

AvatarManager loads avatar assets by Avatar ID and returns the Avatar object AvatarKit can render. It also owns the shared client-side load state:
  • In-flight loads are reused for the same Avatar ID.
  • Successful loads are cached.
  • Cancel and release operations affect shared AvatarManager state, so coordinate them with any view still using the same Avatar.
→ Reference: Web AvatarManager · iOS AvatarManager · Android AvatarManager

​
AvatarView and AvatarController

Loading an Avatar does not display it. You mount the loaded Avatar in an AvatarView. AvatarView creates the render surface and owns the AvatarController for that surface. From there:
  • AvatarView displays the loaded Avatar.
  • AvatarController controls playback, connection, state, and interruption.
  • When motion data arrives, AvatarKit applies it to the mounted Avatar.
For the full session order, see Sessions & Lifecycle. → Reference: Web Avatar · iOS Avatar · Android Avatar

​
What can go wrong

SymptomLikely cause
Avatar never appearsBad Avatar ID, failed asset download, or missing AvatarView mount.
Loading never completesNetwork failure or an in-flight load that never resolves.
Avatar disappears after cleanupShared cached assets were released while another view still needed them.
Audio plays but the avatar does not moveThe Avatar loaded, but the session connection or motion data path is not online.

​
Go next