Skip to main content

Core concepts

The API is built around two objects: identities and sessions. An identity is the avatar; a session is the live conversation that brings it to life.

Identity​

An identity is one avatar. It bundles everything that makes the avatar itself:

  • a personality (a system prompt that shapes how it speaks and behaves)
  • a voice
  • a visual appearance

The guiding rule is:

one avatar = one identity_id

You never manage separate voice_id, visual_id, or provider asset IDs. You create an identity from reference media, and from then on refer to it by its identity_id everywhere. Example: id_8f2c10ab.

Once created, an identity onboards automatically — moving through created → training → ready on its own, with no separate step for you to kick off. Just poll its status until it reports ready; only a ready identity can be used in a session. (Onboarding an identity draws on your account's credits — see Billing & credits.)

Session​

A session is a live conversation for one identity. You open it with POST /v1/sessions/start and join over LiveKit; the avatar then listens and responds in real time.

Under the hood a session is made up of messages — the individual turns of the conversation. You don't manage these yourself: the realtime API handles them natively, capturing what the user says and generating the avatar's spoken replies turn by turn. A session can hold a single turn or many over time. Example: sess_4b9e02f1.